# Glossary source: https://developer.mastercard.com/merchant-identifier/documentation/glossary/index.md ## Glossary {#glossary} This page defines the terms used throughout the Merchant Identifier API documentation. Terms are grouped by topic, and each entry links to the page where the concept is covered in full. ## Core Concepts {#core-concepts} | Term | Definition | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Merchant Identifier API** | Mastercard API that resolves raw merchant information, such as a transaction descriptor or an acquirer-assigned identifier, into a standardized merchant record. See the [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md). | | **Match and append** | The methodology behind the API. Using the input criteria you provide, the API first *matches* the merchant location within Mastercard's merchant reference dataset, then *appends* select attributes about that merchant to the response payload. See the [Endpoint Overview](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/index.md). | | **Location ID** | Unique Mastercard-defined identifier for a merchant location, returned as `locationId`. Each distinct ID corresponds to a single merchant store, and the ID links that merchant across all Mastercard products and services. It can be passed to the [Places API](https://developer.mastercard.com/places/documentation/) for richer location-level attributes. | | **Enrichment** | The act of adding verified merchant attributes, such as standardized name, category, and location, to a record that originally contained only raw or partial data. | | **Merchant reference dataset** | Mastercard's global dataset of businesses that accept Mastercard, against which input criteria are matched. | ## Payment Industry Identifiers {#payment-industry-identifiers} | Term | Definition | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Merchant descriptor (DE43)** | The raw text string identifying a merchant on a cardholder's statement, typically a concatenation of merchant name, city, and state. Used as input to `GET /merchants` and returned as `merchantDescriptor`. | | **Card acceptor ID (DE42)** | A unique 15-character code assigned by an acquiring bank to identify a merchant within the Mastercard payment network. Also known as the Acquirer Merchant ID or MID. Used as input to `GET /merchants-by-card-acceptor-ids` and returned as `cardAcceptorId`. | | **Tax ID** | A merchant tax identification number issued by a government authority, used for tax-based matching via `GET /merchants-by-tax-ids` and returned as `taxId`. Currently supported for merchants in Brazil only. | | **Merchant Category Code (MCC)** | Four-digit code classifying a merchant's line of business, as reported in the transaction clearing record. Returned as `merchantCategory` with its description, for example `5533 - AUTOMOTIVE PARTS ACCESSORIES STORES`. | | **Acquirer** | The financial institution that holds the relationship with a merchant and processes card transactions on the merchant's behalf. Acquirers assign card acceptor IDs. | | **Clearing record** | The transaction record exchanged between acquirer and issuer after authorization. Several Merchant Identifier fields, including the descriptor and MCC, originate from clearing data. | Tip: Not sure which identifier you hold, or which endpoint it maps to? The [Endpoint Overview](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/index.md) walks through that decision. ## Data Quality and Matching {#data-quality-and-matching} | Term | Definition | |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Scrubbing** | Mastercard's process of improving the readability of raw data. Includes basic operations such as removing whitespace and eliminating extraneous characters. See [Data Elements](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/data-elements/index.md). | | **Cleansing** | Mastercard's proprietary process of enhancing populated values for a data field. Performed by matching against third-party data sources, standardization, and applying rules and data science techniques to present the best possible field values. | | **Match confidence score** | Indicator of match strength returned by the descriptor matching engine as `matchConfidenceScore`, expressed as a percentage from `0` to `100`. Produced by a proprietary fuzzy match algorithm. | | **Match probability** | Statistical probability returned by the AI-powered endpoint as `matchProbability`, expressed as a value between `0` and `1` indicating the model's confidence in the match. | | **Exact match** | A matching mode that requires the input to correspond precisely to a stored value. Controlled on `GET /merchants` by the `match_type` parameter, which defaults to `ExactMatch`. Tax ID lookup is always an exact match, so it returns no confidence score. | | **Fuzzy matching** | Matching that tolerates minor differences between input and stored values, returning a confidence score rather than a binary result. | | **Semantic matching** | AI-driven matching that interprets the contextual signals within an input rather than relying on character-level similarity. Resilient to truncated, reordered, or inconsistently formatted data. See [Search - AI Powered](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/search-with-ai/index.md). | | **Structured input** | An AI-search request mode in which merchant attributes are supplied across their respective fields, such as `merchantName`, `streetAddress`, and `cityName`, and evaluated collectively. | | **Unstructured input** | An AI-search request mode in which all available merchant details are supplied as a single space-delimited string in the `merchantName` field. | ## Merchant Attributes {#merchant-attributes} | Term | Definition | |---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Merchant name** | Scrubbed merchant name taken from transaction clearing data, returned as `merchantName`. | | **Merchant DBA name** | The public-facing "Doing Business As" name of the merchant, returned as `merchantDbaName`. | | **Brand name** | Cleansed, standardized brand name of the merchant, returned as `brandName`. | | **Legal corporate name** | The merchant legal name as it appears in the clearing record, returned as `legalCorporateName`. | | **Country subdivision** | The state, province, or administrative subdivision of the merchant's location. Returned as `countrySubdivision` for the name and `countrySubdivisionCode` for the ISO 3166-2 code. | | **Brick and mortar flag** | Boolean `isBrickAndMortar`, indicating whether the descriptor is used by the merchant for card-present transactions at a physical location. | | **E-commerce flag** | Boolean `isEcommerce`, indicating whether the descriptor is used by the merchant for card-not-present, online transactions. | For the complete field-by-field reference, see [Data Elements](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/data-elements/index.md). ## API and Integration {#api-and-integration} | Term | Definition | |---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Sandbox** | A shared test environment that mirrors production and is available to everyone who creates a project. All data is mocked but representative. Base URL `https://sandbox.api.mastercard.com/merchant-identifier`. | | **Production** | The live environment returning real merchant data. Base URL `https://api.mastercard.com/merchant-identifier`. Requires approved production access. | | **Free Trial Access** | Production evaluation offer providing up to 10,000 API calls during the first 28 days, with no auto-renewal, so teams can validate value before contracting. | | **OAuth 1.0a** | The authentication scheme Mastercard uses. Every request must be signed with your RSA private key. See [API Basics](https://developer.mastercard.com/merchant-identifier/documentation/api-basics/index.md). | | **Body hash extension** | An OAuth extension that includes a hash of the request body in the signature. Required for requests that carry a body, such as `POST /merchants/searches`. | | **Consumer key** | The public identifier for your project, supplied in the OAuth `Authorization` header. Available on your [Developer Dashboard](https://developer.mastercard.com/dashboard). | | **Signing key** | The RSA private key used to sign API requests, distributed in a password-protected `.p12` keystore. Never share this key or its password. | | **OpenAPI specification** | The machine-readable contract describing every endpoint, parameter, schema, and response. Used to generate client libraries. See the [specification file](https://static.developer.mastercard.com/content/merchant-identifier/swagger/merchantidentifier-v3.yaml). | Warning: Never share your `.p12` keystore, keystore password, or a full `Authorization` header in a support case or email. See [Support](https://developer.mastercard.com/merchant-identifier/documentation/support/index.md). ## Error Handling {#error-handling} | Term | Definition | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Source** | The application that generated an error. A value other than `merchant-identifier-api` means the error came from somewhere other than the Merchant Identifier API. | | **Reason code** | A unique constant identifying the error case encountered during processing, such as `INVALID_INPUT_VALUE` or `TOO_MANY_MATCHES`. | | **Recoverable** | Boolean indicating whether retrying the request could change the outcome. Invalid input is not recoverable; a transient timeout is. | | **Details** | Optional detailed information about data received and calculated during request processing, provided to help diagnose errors. | | **Gateway error** | An error returned by the Mastercard gateway, which verifies your request signature and routes the call, rather than by the Merchant Identifier service itself. See [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes). | For the full list of status codes and Merchant Identifier specific reason codes, see [Codes and Formats](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md). ## Related Mastercard Services {#related-mastercard-services} | Term | Definition | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Places API** | A complementary Mastercard API that returns rich merchant attributes for a known Location ID or a geographic search. Commonly chained after Merchant Identifier: cleanse with Merchant Identifier, then enrich with [Places](https://developer.mastercard.com/places/documentation/). | ## Useful Links {#useful-links} * [Data Elements](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/data-elements/index.md) for the full response field reference * [Endpoint Overview](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/endpoint-overview/index.md) for endpoint-level detail * [Codes and Formats](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md) for error codes and resolutions * [Support](https://developer.mastercard.com/merchant-identifier/documentation/support/index.md) for frequently asked questions