openapi: 3.0.1
info:
  title: Merchant Identifier API
  description: Retrieve merchant data by providing any of the following identifier fields and keys.   Descriptor, Card Acceptor ID, or Tax ID
  contact:
    name:  API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 3.0.4
servers:
  - url: https://api.mastercard.com/merchant-identifier
    description: Production server
  - url: https://sandbox.api.mastercard.com/merchant-identifier
    description: Sandbox server
tags:
  - name: Merchants
    description: API for Merchant Identifier
paths:
  /merchants/searches:
    post:
      tags:
        - Merchants
      summary: 'Search for merchants using AI '
      description: 'Returns detailed information on merchants based on the provided input data'
      operationId: searchMerchantsUsingPOST
      requestBody:
        $ref: '#/components/requestBodies/MerchantSearchList'
      responses:
        '200':
          $ref: '#/components/responses/MerchantBySearchList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /merchants:
    get:
      tags:
        - Merchants
      summary: Get matched merchants for a given merchant descriptor
      description: Returns merchant details for matched merchants given a merchant descriptor as input. (IMPORTANT - Please remove all spaces from the merchant descriptor before submitting your API request)
      operationId: getMerchants
      parameters:
        - $ref: '#/components/parameters/MerchantDescriptorParam'
        - $ref: '#/components/parameters/MatchTypeParam'
      responses:
        '200':
          $ref: '#/components/responses/MerchantList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /merchants-by-card-acceptor-ids:
    get:
      tags:
        - Merchants
      summary: Get matched merchant information for a given card acceptor id
      description: Returns merchant details for matched merchants given a card acceptor id and optional country code.  (IMPORTANT - Only card acceptor ids that can be uniquely mapped to one merchant location are accepted)
      operationId: getMerchantByCardAcceptorId
      parameters:
        - $ref: '#/components/parameters/MerchantCardAcceptorIdParam'
        - $ref: '#/components/parameters/MerchantCardAcceptorCountry'
      responses:
        '200':
          $ref: '#/components/responses/MerchantByCardAcceptorIdList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /merchants-by-tax-ids:
    get:
      tags:
        - Merchants
      summary: Get merchant information for a given tax id
      description: Returns a list merchants details for matched merchant given a tax id
      operationId: getMerchantByTaxId
      parameters:
        - $ref: '#/components/parameters/TaxId'
        - $ref: '#/components/parameters/Country'
      responses:
        '200':
          $ref: '#/components/responses/MerchantByTaxIdList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
components:
  requestBodies:
    MerchantSearchList:
      description: Merchant search input list.  At this time only one merchant can be queried at a time
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantSearchList'
  parameters:
    MerchantDescriptorParam:
      name: merchant_descriptor
      in: query
      description: The Merchant Descriptor being queried
      required: true
      schema:
        type: string
      example: 'DOLIUMPTYLTDWELSHPOOLWA'
    MatchTypeParam:
      name: match_type
      in: query
      description: The type of match to perform
      schema:
        type: string
        default: 'ExactMatch'
      example: 'ExactMatch'
    MerchantCardAcceptorIdParam:
      name: card_acceptor_id
      in: query
      description: Card Acceptor Id
      required: true
      schema:
        type: string
      example: 'C928456'
    MerchantCardAcceptorCountry:
      name: country_code
      description: ISO 3166-1 alpha-3 country code of card acceptor id
      in: query
      required: false
      schema:
        type: string
      example: 'USA'
    Country:
      name: country_code
      description: ISO 3166-1 alpha-3 country code of tax id
      in: query
      required: true
      schema:
        type: string
      example: 'BRA'
    TaxId:
      name: tax_id
      description: The tax id assigned by government entity for location
      in: query
      required: true
      schema:
        type: string
      example: '29152490000123'
  schemas:
    MerchantSearch:
      title: Merchant Search input structure
      type: object
      properties:
        merchantName:
          type: string
          description: The name of merchant being queried
          example: 'DOLIUM PTY LTD'
        streetAddress:
          type: string
          description: The street address of the merchant being queried.  Should include the street number and name, but not city, state, or postal code
          example: 'UNIT 2 248 WELSHPOOL RD'
        cityName:
          type: string
          description: The city where the merchant being queried is located
          example: 'Springfield'
        postalCode:
          type: string
          description: The postal code associated with the merchant’s location
          example: '92648'
        stateProvinceCode:
          type: string
          description: The state or province code of the merchant being queried.
          example: 'Springfield'
        countryCode:
          type: string
          description: The country code of the merchant being queried.
          example: 'USA'
        phoneNumber:
          type: string
          description: The phone number for the merchant.
          example: '555-142-7943'
        url:
          type: string
          description: The merchant’s website or primary online presence URL
          example: 'WWW.DOLIUMPTYLTD.COM'
      description: Merchant Search Request
    Address:
      description: Available information for this Address such as the street, city, country, country subdivision an postal code.
      type: object
      properties:
        city:
          type: string
          description: Name of the city or town where the merchant is located
          example: WELSHPOOL
        country:
          $ref: '#/components/schemas/Country'
        countrySubdivision:
          $ref: '#/components/schemas/CountrySubDivision'
        line1:
          type: string
          description: Line 1 of the street address of the merchant. Usually includes the street number and name
          example: UNIT 2 248 WELSHPOOL RD
        line2:
          type: string
          description: Line 2 of the street address, usually an apartment number or suite number
          example: "12"
        postalCode:
          type: string
          description: The zip code or postal code for a merchant
          example: "6106"
      example:
        country:
          code: 'AUS'
          name: 'Australia'
        countrySubdivision:
          code: 'WA'
          name: 'Western Australia'
        line1: 'UNIT 2 248 WELSHPOOL RD'
        line2: '12'
        postalCode: '6106'
    Country:
      description: Available information the Country such as the name and code
      type: object
      properties:
        code:
          type: string
          description: Three digit alpha country code as defined in ISO 3166-1
          example: 'AUS'
        name:
          type: string
          description: Name of the country
          example: 'Australia'
      example:
        Country:
          code: 'AUS'
          name: 'Australia'
    CountrySubDivision:
      description: Available information the Country Subdivision such as the name and code
      type: object
      properties:
        code:
          type: string
          description: Abbreviated code for the state or province
          example: 'WA'
        name:
          type: string
          description: Name of the state or province
          example: 'Western Australia'
      example:
        CountrySubDivision:
          code: 'WA'
          name: 'Western Australia'
    Error:
      description: Details of the error condition such as the source of the error, reason code for the error,
        if the error is recoverable, and details about the error
      required:
        - Description
        - ReasonCode
        - Recoverable
        - Source
      type: object
      properties:
        Source:
          description: The application that generated this error
          type: string
          minLength: 0
          maxLength: 150
          example: 'merchantid'
        ReasonCode:
          description: A unique constant identifying the error case encountered during transaction processing
          type: string
          minLength: 0
          maxLength: 150
          example: 'TOO_MANY_MATCHES'
        Description:
          description: Short description of the ReasonCode field
          type: string
          minLength: 0
          maxLength: 150
          example: 'Too many matches found.  Please refine search input'
        Recoverable:
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          type: boolean
          example: 'false'
        Details:
          description: Description of the issue
          example: 'The search resulted in too many matches'
          type: string
          minLength: 0
          maxLength: 150
          nullable: true
    ErrorResponse:
      description: Only returned in the event of an error condition
      required:
        - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    Errors:
      description: 'Only returned in the event of an error condition'
      required:
        - Error
      type: object
      properties:
        Error:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: 'An error object'
          example:
            - Error:
                Source: merchant_descriptor
                ReasonCode: INVALID_INPUT_VALUE
                Description: "merchant_descriptor must be greater than 10 characters"
                Recoverable: false
                Details: null
      example:
        Errors:
          - Error:
              Source: merchant_descriptor
              ReasonCode: INVALID_INPUT_VALUE
              Description: "merchant_descriptor must be greater than 10 characters"
              Recoverable: false
              Details: null
    Merchant:
      description: Available information the merchant such as Address, matchConfidenceScore, and locationId
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        brandName:
          type: string
          description: The brand name of the merchant
          example: 'DOLIUM PTY LTD'
        merchantDescriptor:
          type: string
          description: Descriptor for the merchant provided by the Merchant Service
            Provider(MSP)
          example: 'DOLIUMPTYLTDWELSHPOOLWA'
        legalCorporateName:
          type: string
          description: Corporate legal name of the merchant
          example: DOLIUM PTY LTD
        locationId:
          type: integer
          description: Merchant specific location identifier
          format: int32
          example: 344147943
        matchConfidenceScore:
          type: integer
          description: Confidence score (%) to help clients understand the quality
            of the search results
          format: int32
          example: 100
        merchantCategory:
          type: string
          description: Merchant category code and description associated with the
            merchant category code for the merchant
          example: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
        merchantDbaName:
          type: string
          description: The business name of the merchant
          example: DOLIUM PTY LTD
        phoneNumber:
          type: string
          description: The phone number of the merchant
          example: "893582575"
        isBrickAndMortar:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for brick-and-mortar (card-present) transactions
          example: true
        isEcommerce:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for e-commerce (card-not-present) transactions
          example: true
    MerchantBySearch:
      description: Available information the merchant such as Address, matchProbability, and locationId
      type: object
      properties:
        merchantName:
          type: string
          description: The business name of the merchant
          example: DOLIUM PTY LTD
        matchProbability:
          type: number
          description: Confidence score (%) to help clients understand the quality
            of the search results
          format: double
          example: 0.99
        streetAddress:
          type: string
          description: The street address of the merchant being queried.  Should include the street number and name, but not city, state, or postal code
          example: '123 Fake Street'
        cityName:
          type: string
          description: The city where the merchant is located
          example: 'Springfield'
        postalCode:
          type: string
          description: The postal code associated with the merchant’s location
          example: '122345'
        countrySubdivisionCode:
          type: string
          description: The state or province code of the merchant.
          example: 'NY'
        countrySubdivisionName:
          type: string
          description: The state or province name of the merchant.
          example: 'New Yor'
        countryCode:
          type: string
          description: The country code of the merchant.
          example: 'USA'
        countryName:
          type: string
          description: The country Name of the merchant.
          example: 'United States'
        brandName:
          type: string
          description: The brand name of the merchant
          example: 'DOLIUM PTY LTD'
        legalCorporateName:
          type: string
          description: Corporate legal name of the merchant
          example: DOLIUM PTY LTD
        locationId:
          type: integer
          description: Merchant specific location identifier
          format: int32
          example: 344147943
        merchantCategory:
          type: string
          description: Merchant category code and description associated with the
            merchant category code for the merchant
          example: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
        phoneNumber:
          type: string
          description: The phone number of the merchant
          example: "893582575"
        isBrickAndMortar:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for brick-and-mortar (card-present) transactions
          example: true
        isEcommerce:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for e-commerce (card-not-present) transactions
          example: true
        url:
          type: string
          description: The merchant’s website or primary online presence URL
          example: 'www.myurl.com'
    MerchantByCardAcceptorId:
      description: Available information the merchant such as Address, matchConfidenceScore, and locationId
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        brandName:
          type: string
          description: The brand name of the merchant
          example: 'DOLIUM PTY LTD'
        cardAcceptorId:
          type: string
          description: The Card Acceptor ID assigned by the acquirer
          example: 'C928456'
        legalCorporateName:
          type: string
          description: Corporate legal name of the merchant
          example: DOLIUM PTY LTD
        locationId:
          type: integer
          description: Merchant specific location identifier
          format: int32
          example: 344147943
        merchantCategory:
          type: string
          description: Merchant category code and description associated with the
            merchant category code for the merchant
          example: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
        merchantDbaName:
          type: string
          description: The business name of the merchant
          example: DOLIUM PTY LTD
        phoneNumber:
          type: string
          description: The phone number of the merchant
          example: "893582575"
        isBrickAndMortar:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for brick-and-mortar (card-present) transactions
          example: true
        isEcommerce:
          type: boolean
          description: Indicates whether the input descriptor is used by the merchant for e-commerce (card-not-present) transactions
          example: true
    MerchantByTaxId:
      description: Available information for the merchant such as Address, and locationId
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        brandName:
          type: string
          description: The brand name of the merchant
          example: 'DOLIUM PTY LTD'
        taxId:
          type: string
          description: The tax id assigned by government entity for location
          example: '29152490000123'
        legalCorporateName:
          type: string
          description: Corporate legal name of the merchant
          example: DOLIUM PTY LTD
        locationId:
          type: integer
          description: Merchant specific location identifier
          format: int32
          example: 344147943
        merchantCategory:
          type: string
          description: Merchant category code and description associated with the
            merchant category code for the merchant
          example: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
        merchantDbaName:
          type: string
          description: The business name of the merchant
          example: DOLIUM PTY LTD
        phoneNumber:
          type: string
          description: The phone number of the merchant
          example: "893582575"
    MerchantList:
      description: List of merchants
      type: object
      properties:
        merchants:
          type: array
          description: merchants
          items:
            $ref: '#/components/schemas/Merchant'
          example:
            -  matchConfidenceScore: 100
               address:
                 line1: 'UNIT 2 248 WELSHPOOL RD'
                 line2: '12'
                 city : 'Springfield'
                 postalCode: '6106'
                 country:
                   code: 'AUS'
                   name: 'Australia'
                 countrySubdivision:
                   code: 'WA'
                   name: 'Western Australia'
               brandName: 'DOLIUM PTY LTD'
               phoneNumber: "893582575"
               merchantCategory: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
               merchantDbaName: 'DOLIUM PTY LTD'
               merchantDescriptor: 'DOLIUMPTYLTDWELSHPOOLWA'
               legalCorporateName: 'DOLIUM PTY LTD'
               locationId: 344147943
               isBrickAndMortar: true
               isEcommerce: true
    MerchantSearchList:
      description: List of merchants
      type: object
      properties:
        merchants:
          type: array
          description: merchants
          items:
            $ref: '#/components/schemas/MerchantSearch'
          example:
            -  merchantName: 'DOLIUM PTY LTD'
               streetAddress: 'UNIT 2 248 WELSHPOOL RD'
               cityName: 'Springfield'
               postalCode: '92648'
               stateProvinceCode: 'MO'
               countryCode: 'USA'
               phoneNumber: '123-123-1223'
               url: 'WWW.DOLIUMPTYLTD.COM'
    MerchantBySearchList:
      description: List of merchants
      type: object
      properties:
        merchants:
          type: array
          description: merchants
          items:
            $ref: '#/components/schemas/MerchantBySearch'
          example:
            -  merchantName: 'DOLIUM PTY LTD'
               matchProbability: 0.95
               streetAddress: 'UNIT 2 248 WELSHPOOL RD'
               cityName: 'Springfield'
               postalCode: '92648'
               countryCode: 'USA'
               countryName: 'UNITED STATES'
               countrySubdivisionCode: 'MO'
               countrySubdivisionName: 'MISSOURI'
               brandName : 'DOLIUM PTY LTD'
               phoneNumber: "344147943"
               merchantCategory: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
               legalCorporateName: 'DOLIUM PTY LTD'
               locationId: 463275395
               isBrickAndMortar: true
               isEcommerce: true
               url: 'WWW.DOLIUMPTYLTD.COM'
    MerchantByCardAcceptorIdList:
      description: List of merchants
      type: object
      properties:
        merchants:
          type: array
          description: merchants
          items:
            $ref: '#/components/schemas/MerchantByCardAcceptorId'
          example:
            -  address:
                 line1: 'UNIT 2 248 WELSHPOOL RD'
                 line2: '12'
                 city : 'Springfield'
                 postalCode: '6106'
                 country:
                   code: 'AUS'
                   name: 'Australia'
                 countrySubdivision:
                   code: 'WA'
                   name: 'Western Australia'
               brandName: 'DOLIUM PTY LTD'
               phoneNumber: "893582575"
               merchantCategory: '5533 - AUTOMOTIVE PARTS  ACCESSORIES STORES'
               merchantDbaName: 'DOLIUM PTY LTD'
               cardAcceptorId: 'C928456'
               legalCorporateName: 'DOLIUM PTY LTD'
               locationId: 344147943
               isBrickAndMortar: true
               isEcommerce: true
    MerchantByTaxIdList:
      description: List of merchants
      type: object
      properties:
        merchants:
          type: array
          description: merchants
          items:
            $ref: '#/components/schemas/MerchantByTaxId'
          example:
            - address:
                line1: 'RUA ORATORIO  760'
                city: 'SANTO ANDRÉ'
                postalCode: '09280-550'
                country:
                  code: 'BRA'
                  name: 'BRAZIL'
                countrySubdivision:
                  code: 'SP'
              brandName: 'NON-AGGREGATED MISC FOOD STORE-CONVENIENCE MRKT SPLTY VENDNG 5499'
              merchantCategory: '5499 - MISC FOOD STORE-CONVENIENCE MRKT SPLTY VENDNG MACS'
              merchantDbaName: 'PIZZARIA VENEZA'
              taxId: '29152490000123'
              locationId: 555893050
  responses:
    MerchantBySearchList:
      description: Information for this merchant identifier search
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantBySearchList'
    MerchantList:
      description: Information for this merchant identifier
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantList'
    MerchantByCardAcceptorIdList:
      description: Information for this merchant identifier
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantByCardAcceptorIdList'
    MerchantByTaxIdList:
      description: Information for this merchant identifier
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantByTaxIdList'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
              - Error:
                  Source: merchant_descriptor
                  ReasonCode: INVALID_INPUT_VALUE
                  Description: "merchant_descriptor must be greater than 10 characters"
                  Recoverable: false
                  Details: null
    UnauthorizedError:
      description: Authentication information was missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
              - Error:
                  Source: merchantidentifier-api
                  ReasonCode: UNAUTHORIZED
                  Description: "We couldn't recognize you"
                  Recoverable: false
                  Details: "Full authentication is required to access this resource"
    ForbiddenError:
      description: Insufficient permissions for interacting with the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
              - Error:
                  Source:  merchantidentifier-api
                  ReasonCode: PERMISSION_DENIED
                  Description: "You don't seem authorized to do that"
                  Recoverable: false
                  Details: "Reading merchant information requires readonly permissions"