Mastercard · Schema

Mastercard Merchant

A merchant or card acceptor registered in the Mastercard network. Represents businesses that accept Mastercard payments, with location, categorization, and terminal capability data. Used across Merchant Locations, Checkout Solutions, fraud reporting, and analytics APIs.

Credit CardsDigital IdentityFinancial ServicesFraud DetectionOpen BankingPaymentsFortune 500

Properties

Name	Type	Description
merchantId	string	Card acceptor or merchant unique identification number assigned by the acquirer.
id	integer	Numerical merchant identifier within the Mastercard Merchant Locations system.
merchantName	string	Legal or trade name of the merchant.
dbaName	string	Doing Business As (DBA) name, the merchant name visible to cardholders.
merchantCategoryCode	string	Four-digit ISO 18245 Merchant Category Code (MCC) classifying the business type.
category	string	Human-readable merchant category description from the Mastercard category taxonomy.
categoryId	string	Mastercard internal category identifier for the merchant.
merchantType	string	Classification of the merchant by acceptance capability.
address	object
location	object
distance	number	Distance from a search reference point to this merchant location.
distanceUnit	string	Unit of measure for the distance value.
geocodingResult	string	Geocoding result quality indicator for the merchant address.
terminalCapabilities	object
cashbackMaximumAmount	string	Maximum cashback amount permitted at this merchant location.
dpa	object
acquirerId	string	ICA number of the acquiring institution for this merchant.
acquirerMerchantId	string	Merchant identifier assigned by the acquirer.
websiteUrl	string	URL of the merchant website.
logoUrl	string	URL of the merchant logo image.
offerMerchantId	string	Unique identifier representing the merchant as a sponsor of offers.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "https://github.com/api-evangelist/mastercard/blob/main/json-schema/merchant.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Mastercard Merchant",
  "description": "A merchant or card acceptor registered in the Mastercard network. Represents businesses that accept Mastercard payments, with location, categorization, and terminal capability data. Used across Merchant Locations, Checkout Solutions, fraud reporting, and analytics APIs.",
  "type": "object",
  "required": [
    "merchantId",
    "merchantName"
  ],
  "properties": {
    "merchantId": {
      "type": "string",
      "description": "Card acceptor or merchant unique identification number assigned by the acquirer.",
      "minLength": 1,
      "maxLength": 15,
      "examples": ["A42E51982100100"]
    },
    "id": {
      "type": "integer",
      "description": "Numerical merchant identifier within the Mastercard Merchant Locations system.",
      "format": "int32",
      "examples": [1505451132]
    },
    "merchantName": {
      "type": "string",
      "description": "Legal or trade name of the merchant.",
      "minLength": 1,
      "maxLength": 100,
      "examples": ["Ecom Holdings Online Inc"]
    },
    "dbaName": {
      "type": "string",
      "description": "Doing Business As (DBA) name, the merchant name visible to cardholders.",
      "maxLength": 100
    },
    "merchantCategoryCode": {
      "type": "string",
      "description": "Four-digit ISO 18245 Merchant Category Code (MCC) classifying the business type.",
      "pattern": "^[0-9]{4}$",
      "minLength": 4,
      "maxLength": 4,
      "examples": ["5411"]
    },
    "category": {
      "type": "string",
      "description": "Human-readable merchant category description from the Mastercard category taxonomy.",
      "examples": ["10 - Grocery Stores & Supermarkets"]
    },
    "categoryId": {
      "type": "string",
      "description": "Mastercard internal category identifier for the merchant.",
      "minLength": 1,
      "maxLength": 2,
      "examples": ["10"]
    },
    "merchantType": {
      "type": "string",
      "description": "Classification of the merchant by acceptance capability.",
      "enum": [
        "paypass",
        "repower",
        "easysavings",
        "cashback"
      ]
    },
    "address": {
      "$ref": "#/$defs/MerchantAddress"
    },
    "location": {
      "$ref": "#/$defs/GeoLocation"
    },
    "distance": {
      "type": "number",
      "description": "Distance from a search reference point to this merchant location.",
      "format": "double",
      "examples": [1.75723]
    },
    "distanceUnit": {
      "type": "string",
      "description": "Unit of measure for the distance value.",
      "enum": ["MILE", "KM"],
      "examples": ["MILE"]
    },
    "geocodingResult": {
      "type": "string",
      "description": "Geocoding result quality indicator for the merchant address.",
      "examples": ["S8HPNTSCZA"]
    },
    "terminalCapabilities": {
      "$ref": "#/$defs/TerminalCapabilities"
    },
    "cashbackMaximumAmount": {
      "type": "string",
      "description": "Maximum cashback amount permitted at this merchant location.",
      "examples": ["40"]
    },
    "dpa": {
      "$ref": "#/$defs/DigitalPaymentApplication"
    },
    "acquirerId": {
      "type": "string",
      "description": "ICA number of the acquiring institution for this merchant.",
      "minLength": 3,
      "maxLength": 7
    },
    "acquirerMerchantId": {
      "type": "string",
      "description": "Merchant identifier assigned by the acquirer.",
      "maxLength": 15,
      "examples": ["M123456"]
    },
    "websiteUrl": {
      "type": "string",
      "description": "URL of the merchant website.",
      "format": "uri",
      "examples": ["https://example.com/ecom-online-ltd/basket.html"]
    },
    "logoUrl": {
      "type": "string",
      "description": "URL of the merchant logo image.",
      "format": "uri",
      "examples": ["https://example.com/ecom-online-ltd/images/ecom-logo.png"]
    },
    "offerMerchantId": {
      "type": "string",
      "description": "Unique identifier representing the merchant as a sponsor of offers.",
      "examples": ["1143109"]
    }
  },
  "$defs": {
    "MerchantAddress": {
      "type": "object",
      "description": "Physical or mailing address of a merchant location.",
      "properties": {
        "addressLine1": {
          "type": "string",
          "description": "First line of the street address, usually including street number and name.",
          "examples": ["4033 Veterans Memorial Pkwy"]
        },
        "addressLine2": {
          "type": "string",
          "description": "Second line of the street address, such as suite or apartment number.",
          "examples": ["Apt 1"]
        },
        "city": {
          "type": "string",
          "description": "City name of the merchant location.",
          "examples": ["SAINT PETERS"]
        },
        "stateProvinceCode": {
          "type": "string",
          "description": "Two-letter state or province code (US and Canada).",
          "minLength": 2,
          "maxLength": 3,
          "examples": ["MO"]
        },
        "stateProvinceName": {
          "type": "string",
          "description": "Full name of the state or province.",
          "examples": ["Missouri"]
        },
        "postalCode": {
          "type": "string",
          "description": "Postal or ZIP code for the merchant location.",
          "maxLength": 10,
          "examples": ["63376"]
        },
        "countryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-3 or alpha-2 country code for the merchant location.",
          "minLength": 2,
          "maxLength": 3,
          "examples": ["USA"]
        },
        "countryName": {
          "type": "string",
          "description": "Full name of the country.",
          "examples": ["United States"]
        }
      }
    },
    "GeoLocation": {
      "type": "object",
      "description": "Geographic coordinates for a merchant location.",
      "properties": {
        "latitude": {
          "type": "string",
          "description": "Latitude coordinate of the merchant location.",
          "examples": ["38.795089"]
        },
        "longitude": {
          "type": "string",
          "description": "Longitude coordinate of the merchant location.",
          "examples": ["-90.572346"]
        }
      }
    },
    "TerminalCapabilities": {
      "type": "object",
      "description": "Capabilities of terminals at the merchant location.",
      "properties": {
        "isPayPassConcession": {
          "type": "boolean",
          "description": "Whether the concession area is equipped with a PayPass contactless reader."
        },
        "isPayPassPharmacy": {
          "type": "boolean",
          "description": "Whether the pharmacy is equipped with a PayPass contactless reader."
        },
        "isPayPassFuelPump": {
          "type": "boolean",
          "description": "Whether the fuel pump is equipped with a PayPass contactless reader."
        },
        "isPayPassTollBooth": {
          "type": "boolean",
          "description": "Whether the toll booth is equipped with a PayPass contactless reader."
        },
        "isPayPassDriveThrough": {
          "type": "boolean",
          "description": "Whether the drive-through is equipped with a PayPass contactless reader."
        },
        "terminalId": {
          "type": "string",
          "description": "Unique code identifying the terminal at the merchant location.",
          "maxLength": 8
        },
        "terminalAttendanceIndicator": {
          "type": "string",
          "description": "Indicates if the card acceptor was attending the terminal.",
          "maxLength": 1
        },
        "terminalOperatingEnvironment": {
          "type": "string",
          "description": "Operating environment of the terminal (attended, unattended, etc.).",
          "maxLength": 1
        },
        "terminalCapabilityIndicator": {
          "type": "string",
          "description": "Capability of the terminal to read card data.",
          "maxLength": 1
        }
      }
    },
    "DigitalPaymentApplication": {
      "type": "object",
      "description": "A Digital Payment Application (DPA) representing a website or mobile app where consumers can purchase goods using Mastercard SRC (Secure Remote Commerce).",
      "properties": {
        "srcDpaId": {
          "type": "string",
          "description": "Unique identifier for the DPA within the SRC system.",
          "examples": ["src_dpa_56068"]
        },
        "dpaName": {
          "type": "string",
          "description": "Legal name of the DPA operator.",
          "examples": ["Ecom Holdings Online Inc"]
        },
        "dpaPresentationName": {
          "type": "string",
          "description": "Consumer-facing display name of the DPA."
        },
        "programType": {
          "type": "string",
          "description": "The program type for the DPA registration.",
          "enum": ["SRC", "TOKEN"]
        },
        "serviceId": {
          "type": "string",
          "description": "Unique identifier assigned by Mastercard for which tokens are created."
        }
      }
    }
  }
}