# Integration and Testing
source: https://developer.mastercard.com/merchant-identifier/documentation/integration-and-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 merchant locations data, but should not be used in any production system, the values for each location are not applicable to real world configurations.
Warning: The merchant locations data used in sandbox are randomly generated mocked data and should not be treated as being an accurate representation of real world merchant locations.

## Prerequisites {#prerequisites}

Confirm the following before you send any requests:

* Your project is created and Sandbox credentials are available.
* You are using the Sandbox base URL: `https://sandbox.api.mastercard.com/merchant-identifier`
* 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/merchant-identifier/documentation/quick-start-guide/index.md).

## Testing Workflow {#testing-workflow}

Follow this ordered checklist to validate your integration end-to-end. Tests 1 to 4 are positive cases that cover every endpoint, and test 5 is a negative case that confirms the API's error responses are handled correctly.

| # |                      Test                      |               Endpoint                |                                                                                                                                                                                                                                                                       What to Verify                                                                                                                                                                                                                                                                       |
|---|------------------------------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Search for merchants using AI                  | `POST /merchants/searches`            | Send `merchantName` and any available address fields in the JSON request body. Confirm HTTP 200 and a response containing `merchants` with a `locationId` for each match. For test values, see [Sandbox Test Data](https://developer.mastercard.com/merchant-identifier/documentation/integration-and-testing/index.md#sandbox-test-data). To learn more, see [Search -- AI Powered](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/search-with-ai/index.md).                                   |
| 2 | Search for merchants by transaction descriptor | `GET /merchants`                      | Send `merchant_descriptor` as a query parameter, and optionally `match_type`. Confirm HTTP 200 and a response containing `merchants` with a `matchConfidenceScore` and a `locationId`. For test values, see [Sandbox Test Data](https://developer.mastercard.com/merchant-identifier/documentation/integration-and-testing/index.md#sandbox-test-data). To learn more, see [Search -- by Transaction Descriptor](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/search-by-descriptor/index.md). |
| 3 | Look up a merchant by card acceptor ID         | `GET /merchants-by-card-acceptor-ids` | Send `card_acceptor_id` as a query parameter, and optionally `country_code`. Confirm HTTP 200 and a response containing a matched merchant with a `locationId`. For test values, see [Sandbox Test Data](https://developer.mastercard.com/merchant-identifier/documentation/integration-and-testing/index.md#sandbox-test-data). To learn more, see [Lookup -- by Card Acceptor Id](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/lookup-by-acceptor-id/index.md).                             |
| 4 | Look up a merchant by tax ID                   | `GET /merchants-by-tax-ids`           | Send `tax_id` and `country_code` as query parameters. Both are required. Confirm HTTP 200 and a response containing the matched merchant with a `taxId` and a `locationId`. For test values, see [Sandbox Test Data](https://developer.mastercard.com/merchant-identifier/documentation/integration-and-testing/index.md#sandbox-test-data). To learn more, see [Lookup -- by Tax Id](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/lookup-by-tax-id/index.md).                                |
| 5 | Submit an invalid identifier                   | `GET /merchants-by-tax-ids`           | Send an invalid `tax_id` value, or omit the required `country_code` query parameter. Confirm HTTP 400 and an error payload with a `ReasonCode` of `INVALID_INPUT_VALUE` or `MISSING_REQUIRED_INPUT`. To learn more, see [Codes and Formats](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md).                                                                                                                                                                                                                 |

To review the full request and response definitions for each operation, see the [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md).

## Sandbox Test Data {#sandbox-test-data}

For list of sandbox data containing merchant descriptors and card acceptors please click [here](https://static.developer.mastercard.com/content/merchant-identifier/uploads/merchant-identifier-sandbox-merchant-descriptors.xlsx)

## Troubleshooting {#troubleshooting}

For a full list of error codes and their meanings, see [Codes and Formats](https://developer.mastercard.com/merchant-identifier/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 sent to `/merchants/searches`.
* MISSING_REQUIRED_INPUT
* INVALID_INPUT_VALUE
* DESCRIPTOR_TOO_SMALL
* TOO_MANY_MATCHES

<br />

To resolve this error, try the following:

1. Ensure all required query parameters are present. `merchant_descriptor`, `card_acceptor_id`, `tax_id`, and `country_code` are required for their respective endpoints.
2. Validate your JSON payload with a JSON linter.
3. Ensure the merchant descriptor is long enough to provide a meaningful search, and remove all spaces before submitting.
4. Ensure the search query is specific enough to avoid returning too many matches. This happens when the search query is too broad and matches many merchants in the database. Try to provide more specific information in your search query.

## Environment Guidance {#environment-guidance}

For environment URLs and descriptions, see [API Basics - Environments](https://developer.mastercard.com/merchant-identifier/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/merchant-identifier/documentation/quick-start-guide/index.md) if you still need credentials or project setup.
* Use [Developer Tools](https://developer.mastercard.com/merchant-identifier/documentation/developer-tools/index.md) if you want ready-to-run collections.
* Follow the [Endpoint Overview](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/index.md) for detailed information about each operation.
* Browse [Use Cases](https://developer.mastercard.com/merchant-identifier/documentation/use-cases/index.md) to see how clients apply this data.
* Use the [Onboarding Checklist](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/onboarding-checklist/index.md) to plan your move to Production.