# Support
source: https://developer.mastercard.com/merchant-identifier/documentation/support/index.md

## FAQ {#faq}

#### General {#general}

Merchant Identifier helps organizations identify and enrich merchant information associated with payment transactions. The API can help transform raw merchant descriptors and card acceptor data into standardized merchant information, improving transaction clarity, customer experiences, reporting, and analytics. It takes a merchant descriptor (DE43) or an Acquirer Merchant ID (DE42) as input and returns structured merchant details including cleansed name, address, MCC classification, country, and a Mastercard-assigned Location ID that can be chained to the [Places API](https://developer.mastercard.com/places/documentation/) for richer enrichment   
Typical users include: Card issuers, Digital banking applications, Fintech platforms, Acquirers, Payment processors. Know more about Merchant Identifier API on [Overview page](https://developer.mastercard.com/merchant-identifier/documentation/index.md) Merchant Identifier helps organizations:

* Improve cardholder statement descriptions
* Match merchant descriptors to merchant brands
* Enrich transaction data with merchant attributes
* Improve transaction categorization
* Enhance dispute investigation workflows
* Support analytics and reporting use cases

<br />

By enriching transaction information, organizations can provide clearer merchant visibility to end users and internal operations teams. Check [Use Cases](https://developer.mastercard.com/merchant-identifier/documentation/use-cases/index.md) for more information
Merchant Identifier is designed for:

* Card issuers to cleanse cardholder statement descriptors and reduce disputes
* FinTech applications to standardize merchant names for spend categorization
* Acquirers managing merchant portfolios
* Payment processors for enrich transaction data for downstream analytics
* Organizations building customer-facing transaction experiences
The Merchant Identifier (MID) API is most often used to match raw payment transaction data (descriptors or Card Acceptor IDs) to a Mastercard Location ID. The Merchant Identifier API also has an AI-search endpoint for any generic record that is particularly difficult to match (e.g. source data has typos, acronyms, truncations, etc.) while the Places API returns rich merchant attributes for a known Location ID or geographic search. Both APIs are commonly used together to cleanse via Merchant Identifier and enrich merchant details by Places API:

* Use Merchant Identifier API first to obtain the locationId
* Chain the locationId to the Places API for richer attributes

<br />

Learn more about [Places API](https://developer.mastercard.com/places/documentation/)
These are two standard fields present in every Mastercard transaction:

* DE43 (Merchant Descriptor)- the raw text string identifying a merchant on a cardholder's statement, typically a concatenation of merchant name, city, and state
* DE42 (Card Acceptor ID / MID)- a unique 15-character code assigned by an acquiring bank to identify a merchant within the Mastercard payment network

<br />

The Merchant Identifier API supports both inputs via separate endpoints.

* Use `/merchants` when your input is a descriptor (DE43)
* Use `/merchants-by-card-acceptor-ids` when your input is a DE42
Yes, Mastercard offers a 28-day, 10,000-call [free trial](https://developer.mastercard.com/merchant-identifier/documentation/index.md#3-steps-to-access-your-sandbox) of the Merchant Identifier API in production with no auto-renewal.The trial is designed for developers to evaluate the API against production data before committing to a paid license. Beyond the free tier, pricing follows a per-call model with annual license minimums. Custom pricing is available for high-volume use cases. Contact your account manager or Mastercard representative for more information on commercial plans

#### Onboarding {#onboarding}

Access to the Merchant Identifier API begins with a [signup](https://developer.mastercard.com/account/sign-up) to Mastercard Developers account. Once registered, you can create a project, select the Merchant Identifier API, and immediately receive sandbox credentials for evaluation. download your sandbox key. Once sandbox testing is complete, complete company verification using CID or company details \& request production access via the developer portal. Follow detailed steps on [Quick Start Guide](https://developer.mastercard.com/merchant-identifier/documentation/quick-start-guide/index.md) Sandbox and Production URL details are available on [API Basics Page](https://developer.mastercard.com/merchant-identifier/documentation/api-basics/index.md).
* Sandbox

```Sandbox
https://sandbox.api.mastercard.com/merchant-identifier
```

* Production

```Production
https://api.mastercard.com/merchant-identifier
```

Once you submit a production access request via the Mastercard Developers portal, approval typically takes 2--3 business days after administrator validation. You'll receive an email confirmation upon approval. Yes a Data Evaluation Agreement (DEA) is required for free trial access, and a Statement of Work (SOW) is required for full production licensing. New prospects can start with a click-through DEA signed digitally via Mastercard Developers. The fastest path to a successful first call is to use the GET /merchants endpoint with a sample descriptor. This takes under 5 minutes end-to-end using an OAuth SDK.
Prerequisites checklist:

* Mastercard Developers account
* Project created and Merchant Identifier API added
* Sandbox credentials (Consumer Key, .p12 keystore, key alias, keystore password)
* OAuth1 SDK installed for your language

<br />

Follow detailed steps on [Quick Start Guide](https://developer.mastercard.com/merchant-identifier/documentation/quick-start-guide/index.md)
Merchant Identifier API uses OAuth 1.0a signed with RSA (SHA-256) for authentication. Each request must include a signed authorization header generated using your private key from the developer portal. Learn more → [Authentication Guide](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/)

#### Data and Coverage {#data-and-coverage}

Yes, commercial use is permitted under a signed SOW/license agreement. Free-trial usage under a Data Evaluation Agreement (DEA) is restricted to internal evaluation only and cannot be used in production/customer-facing applications. Merchant Identifier API coverage is global wherever Mastercard is accepted, excluding sanctioned markets (Russia, North Korea, Iran). Match quality is highest in North America, Europe, Australia, South Africa, and Brazil. Merchant Identifier data is built on a rolling 12 months of trailing transactions. Historical data (up to 5 years) is available as a custom request via the data feed, priced separately. To know more contact your organization's Account Manager Terms of use are defined in the signed Data Evaluation Agreement (for trial) or Statement of Work (for production). Common restrictions include no bulk data extraction, no resale of raw data to third parties, and attribution to Mastercard where required.

* Review your signed DEA or SOW for specific restrictions
* Contact Mastercard Sales or Legal for clarification on unusual use cases

#### Integration and Troubleshooting {#integration-and-troubleshooting}

Typically one or two calls --- one to the Merchant Identifier API to resolve the merchant's Location ID, and optionally a second call to the Places API to retrieve full attribute details. Clients can cache responses to minimize call volume. Learn more about the [transaction cleansing flow](https://developer.mastercard.com/merchant-identifier/documentation/) The Merchant Identifier API has four endpoints:

* [Search by Merchant Descriptor](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/getMerchants) (Get matched merchants for a given merchant descriptor),
* [AI Powered Search](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/searchMerchantsUsingPOST) (Search for merchants using AI),
* [Lookup by Card Acceptor Id](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/getMerchantByCardAcceptorId) (Get matched merchant information for a given card acceptor id) and
* [Lookup by Tax id](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/getMerchantByTaxId) (Get merchant information for a given tax id).

<br />

Learn more about the endpoints on [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md)
* [Search by Merchant Descriptor](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/getMerchants) Target average response time is less than 1 second per call. Complex descriptor searches may take slightly longer. Recommended client-side timeout is 60 seconds to accommodate edge cases
* [AI Powered Search](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md#tag/Merchants/operation/searchMerchantsUsingPOST) Target average response time is 5 seconds per call. Recommended client-side timeout is 60 seconds to accommodate edge cases
The Merchant Identifier API uses synthetic monitoring to continuously verify that the API is available and functioning as expected. This information is publicly available, allowing you to check uptime and review any recent issues. Check the [Status Page](https://developer.mastercard.com/api-status?environment=production&service=Merchant%20Identifier) to view this information. This error indicates you have exceeded the maximum requests allowed within the current time window. Reduce your request rate, implement client-side throttling, or contact Support to review your license tier. The API returns structured error codes indicating exactly what went wrong and where. Check [Codes and Formats](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md) page to know more about the errors \& steps to fix them. The descriptor input contains fewer than 10 characters.

#### Common causes: {#common-causes}

* Only the merchant name was passed without city/state
* White space was not removed before length validation
* Descriptor was truncated in your upstream data pipeline

#### Solution: {#solution}

* Concatenate name + city + state in that specific order
* Remove all spaces from the concatenated string
* Validate character count is ≥ 10 before submitting
* If state is unavailable, substitute with the country code
* If descriptor is genuinely short (e.g., single-word merchant), consider using the DE42 endpoint instead

#### Common causes: {#common-causes}

* Your consumer key does not match the one in your Mastercard Developers project.
* Your .p12 signing key file password is incorrect or the file is corrupted.
* The 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.

#### Step-by-step solution: {#step-by-step-solution}

1. Go to your [Mastercard Developers](https://developer.mastercard.com/dashboard) project page and verify your consumer key.
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, verify the OAuth signature is computed over the exact request body being sent.
5. Test with the [Postman Collection](https://developer.mastercard.com/merchant-identifier/documentation/developer-tools/postman-collection/index.md) to isolate whether the issue is in your signing implementation.

See [Codes and Formats](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md) for more details.

## Get Help {#get-help}

### Contact us for technical support. {#contact-us-for-technical-support}