# Testing
source: https://developer.mastercard.com/bin-lookup/documentation/testing/index.md

Testing in Sandbox provides access to a rich set of data that mimics what is available in production. The data in sandbox is entirely mocked information that uses realistic account ranges, but should not be used in any production system, the values for each range are **not** applicable to real world configurations.
Warning: The account ranges used in sandbox are randomly generated mocked data and should not be treated as being an accurate representation of real world Mastercard account (BIN) ranges.

## Prerequisites {#prerequisites}

Confirm the following before you send any requests:

* Your project is created and Sandbox credentials are available.
* Your client uses the Sandbox base URL: `https://sandbox.api.mastercard.com/bin-resources`.
* OAuth 1.0a signing is configured correctly.

If you still need onboarding or credential setup, start with the [Quick Start Guide](https://developer.mastercard.com/bin-lookup/documentation/quick-start-guide/index.md).

## Testing Workflow {#testing-workflow}

Follow this ordered checklist to validate your integration end-to-end. For detailed test mock cases see the [Test Cases](https://developer.mastercard.com/bin-lookup/documentation/testing/index.md#test-cases) section.

| # |          Test           |                                Endpoint                                |                                                                                                                                                                                              What to Verify                                                                                                                                                                                              |
|---|-------------------------|------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | **Single BIN Lookup**   | `POST /bin-ranges/account-searches`                                    | Send an `accountRange` in the body of the request. Confirm HTTP 200 and a JSON array with account range details. See [Sample BIN](https://developer.mastercard.com/bin-lookup/documentation/testing/index.md#sample-bin) for testing data. See the [Single Lookup Tutorial](https://developer.mastercard.com/bin-lookup/documentation/tutorials-and-guides/single-lookup/index.md) for more information. |
| 2 | **Pagination (Page 1)** | `POST /bin-ranges?page=1&size=5000`                                    | Confirm response includes `currentPageNumber`, `totalPages`, `totalItems`, and a populated `items` array.                                                                                                                                                                                                                                                                                                |
| 3 | **Pagination (Full)**   | `POST /bin-ranges?page=N&size=5000`                                    | Loop through all pages. Verify total items downloaded matches `totalItems` from metadata. See the [Pagination Tutorial](https://developer.mastercard.com/bin-lookup/documentation/tutorials-and-guides/pagination-tutorial/index.md) for more information.                                                                                                                                               |
| 4 | **Filtering**           | `POST /bin-ranges` with body `[{"key":"customerName","value":"CITI"}]` | Confirm filtered results contain only items where `customerName` contains "CITI". Alternatively, you can use any of the values from the results you received in testing the full download endpoint with pagination. For more information, see the [Filtering Tutorial](https://developer.mastercard.com/bin-lookup/documentation/tutorials-and-guides/filtering-tutorial/index.md).                      |
| 5 | **Delta Updates**       | `GET /bin-ranges/deltas/snapshots/{from_snapshot_id}?page=1&size=5000` | Use a snapshot ID from the last 7 days and confirm `fromSnapshotId`, `toSnapshotId`, pagination metadata, and `operation` values (`I`, `U`, `D`) are returned as expected.                                                                                                                                                                                                                               |

### Sample BIN {#sample-bin}

|    BIN    |
|-----------|
| 99875393  |
| 29214303  |
| 47980829  |
| 66757806  |
| 855153163 |
| 1157111   |
| 966741047 |
| 225108    |
| 932860    |
| 777305770 |

## Test Cases {#test-cases}

### Positive Example {#positive-example}

`POST /bin-ranges/account-searches`

```json
{
  "accountRange": "1125180"
}
```

**Expected result:** `200 OK` and a response with matching account range details.

### Negative Example {#negative-example}

`POST /bin-ranges/account-searches`

```json
{
  "accountRange": "invalid"
}
```

**Expected result:** `400 Bad Request` because "invalid" is not a valid account range.

### Positive Example {#positive-example}

`POST /bin-ranges?page=1&size=5000`

**Expected result:** `200 OK` and first 5,000 items.

### Negative Example {#negative-example}

`POST /bin-ranges?page=1&size=-5000`

**Expected result:** `400 Bad Request` because the number of items must be a positive integer.

### Positive Example {#positive-example}

`POST /bin-ranges`

```json
[
  {
    "key": "customerName",
    "value": "CITI"
  }
]
```

**Expected result:** `200 OK` and a response with matching account range details.

### Negative Example {#negative-example}

`POST /bin-ranges`

```json
[
  {
    "key": "customerNames",
    "value": "CITI"
  }
]
```

**Expected result:** `400 Bad Request` because "customerNames" is not a valid key.

### Positive Example {#positive-example}

`GET /bin-ranges/deltas/snapshots/{from_snapshot_id}` where `{from_snapshot_id}` is a valid `id` from the last 7 days.

**Expected result:** `200 OK` and a response with BIN data that has changed since the specified `id`.

### Negative Example {#negative-example}

`GET /bin-ranges/deltas/snapshots/{from_snapshot_id}` where `{from_snapshot_id}` is not a valid `id` value from the last 7 days.

**Expected result:** `400 Bad Request` because `{from_snapshot_id}` is not a valid snapshot ID.

## Troubleshooting {#troubleshooting}

For a full list of error codes and their meanings, see [Code and Formats](https://developer.mastercard.com/bin-lookup/documentation/code-and-formats/index.md).

### Authentication Errors (HTTP 401) {#authentication-errors-http-401}

The following are common causes of authentication errors:

* Consumer key does not match the one in your Mastercard Developers project.
* Signing key (.p12 file) password is incorrect or the file is corrupted.
* OAuth timestamp is too far from the server time (must be within 5 minutes).
* The request body was modified after the OAuth signature was computed.

<br />

To resolve this error, try the following:

1. Verify your consumer key matches the value on your Mastercard Developers project page.
2. Re-download your .p12 keystore file and confirm the password is correct.
3. Ensure your system clock is synchronized.
4. If using a custom HTTP client, ensure the OAuth signature is computed over the final request body.

### Bad Request Errors (HTTP 400) {#bad-request-errors-http-400}

The following are common causes of bad request errors:

* Missing or malformed JSON request body.
* Invalid `accountRange` value (must be 6--11 numeric digits for single lookup).
* Invalid pagination parameters (`page` \< 1 or `size` not a positive integer).
* Filter `key` does not match a supported field name.

<br />

To resolve this error, try the following:

1. Validate your JSON payload with a JSON linter.
2. For single lookup, ensure `accountRange` is a string of 6--11 digits.
3. For pagination, confirm `page` starts at 1 and `size` is between 1 and 10000.
4. For filtering, verify `key` matches a supported field (e.g., `customerName`, `productCode`, `country.alpha3`). Refer to [API Data Elements](https://developer.mastercard.com/bin-lookup/documentation/tutorials-and-guides/data-elements/api-data-elements/index.md).

### Pagination Mismatches {#pagination-mismatches}

The following are common causes of pagination mismatches:

* Loop exits before all pages are fetched (off-by-one error).
* `size` parameter changes between pages.

<br />

To resolve this issue, try the following:

1. Ensure your loop continues while `currentPageNumber < totalPages`.
2. Keep the `size` parameter consistent across all page requests.
3. After the loop, verify total downloaded items equals `totalItems` from metadata.

### Filtering Returns No Results {#filtering-returns-no-results}

The following are common causes of filtering returning no results:

* Exact-match field used with a partial value (only `customerName` supports fuzzy matching).
* Misspelled filter value.

<br />

To resolve this issue, try the following:

1. For `customerName`, try a shorter substring (e.g., "CITI" instead of "CITIBANK N.A.").
2. For all other fields, use exact values.

## Environment Guidance {#environment-guidance}

For environment URLs and descriptions, see [API Basics - Environments](https://developer.mastercard.com/bin-lookup/documentation/api-basics/index.md#environments).

* Start in sandbox and complete your positive and negative validation there.
* Move to production only after sandbox testing is complete and production access has been approved.

## Next Steps {#next-steps}

* Start with the [Quick Start Guide](https://developer.mastercard.com/bin-lookup/documentation/quick-start-guide/index.md) if you still need credentials or project setup.
* Use [Developer Tools](https://developer.mastercard.com/bin-lookup/documentation/developer-tools/index.md) if you want ready-to-run collections.
* Follow the endpoint tutorials when you are ready to run detailed positive and negative test cases.