swagger: "2.0"
host: api.mastercard.com
basePath: /merchant-id/v2
info:
  contact:
    email: ADS_Data_Services@mastercard.com
    name: ADS Data Services
    url: http://not.applicable.com
  description: API for Merchant Identifier
  title: Merchant Identifier API V2
  version: 2.0.0
  x-artifactId: merchant-identifier
  x-origin:
    - format: swagger
      url: https://developer.mastercard.com/devzone/api/portal/swagger/merchant-identifier
      version: "2.0"
  x-providerName: mastercard.com
  x-serviceName: MerchantIdentifier
consumes:
  - application/json
produces:
  - application/json
paths:
  /merchant-ids:
    get:
      operationId: GetMerchantIdentifiers
      parameters:
        - default: ""
          description: "Merchant's name as provided by the issuer found on a cardholder statement. __Important: Please remove all spaces before submitting a API request.__ \r\n"
          in: query
          name: merchant_id
          required: false
          type: string
          x-example: DOLIUMPTYLTDWELSHPOOLWA
        - default: ExactMatch
          description: "Determines how the search is performed.\r

            \            ExactMatch returns either the one merchant that best fits the description or no results at all.\r

            \            FuzzyMatch returns 0-20 merchants that are similar to the transaction descriptor. \r

            \            If Type is not provided, defaults to ExactMatch.\r

            \            Example: FuzzyMatch"
          in: query
          name: type
          required: false
          type: string
          x-example: ExactMatch
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/MerchantIds"
        "400":
          description: Bad Request
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: Server Error
      summary: "Returns merchant descriptor and locator information based on the criteria you provide.\r

        Information returned includes merchant DBA name, merchant category code (MCC), street address, city, state, postal code, country, and sales channels."
      tags:
        - MerchantIds
      x-samples:
        - name: example_merchant_identifier
          request:
            application/json: |-
              {
                "merchant_id" : "DOLIUMPTYLTDWELSHPOOLWA",
                "type" : "FuzzyMatch"
              }
          response:
            application/json: |-
              {
                "message": "1 merchants found.",
                "returnedMerchants": [
                  {
                    "address": {
                      "line1": "UNIT 2 248 WELSHPOOL RD",
                      "city": "WELSHPOOL",
                      "postalCode": "6106",
                      "countrySubdivision": {
                        "code": "WA"
                      },
                      "country": {
                        "name": "AUSTRALIA",
                        "code": "AUS"
                      }
                    },
                    "phoneNumber": "893582575",
                    "merchantCategory": "5533 - AUTOMOTIVE PARTS ACCESSORIES STORES",
                    "merchantDbaName": "DOLIUM PTY LTD",
                    "descriptorText": "DOLIUMPTYLTDWELSHPOOLWA",
                    "comment": "100",
                    "locationId": "288560095",
                    "matchConfidenceScore": 100
                  }
                ]
              }
definitions:
  Address:
    properties:
      city:
        description: Name of the city or town where the merchant is located.
        type: string
      country:
        $ref: "#/definitions/Country"
        description: Country
      countrySubdivision:
        $ref: "#/definitions/CountrySubdivision"
        description: State or province.
      line1:
        description: Line 1 of the street address of the merchant. Usually includes the street number and name.
        type: string
      line2:
        description: Line 2 of the street address, usually an apartment number or suite number.
        type: string
      postalCode:
        description: The zip code or postal code for an ATM location
        type: string
    type: object
  Country:
    properties:
      code:
        description: Three digit alpha country code as defined in ISO 3166-1
        type: string
      name:
        description: Name of the country
        type: string
    type: object
  CountrySubdivision:
    properties:
      code:
        description: Abbreviated code for the state or province
        type: string
      name:
        description: Name of the state or province.
        type: string
    type: object
  Error:
    description: Error
    properties:
      description:
        description: Description
        type: string
      reasonCode:
        description: Reason for the error
        type: string
      recoverable:
        description: Is the error recoverable
        type: boolean
      source:
        description: Error Source
        type: string
    type: object
  ErrorResponse:
    description: ErrorResponse array of Error return for Open API
    properties:
      errors:
        description: array of Error
        items:
          $ref: "#/definitions/Error"
        type: array
        uniqueItems: false
    type: object
  Merchant:
    properties:
      address:
        $ref: "#/definitions/Address"
        description: Address of the merchant
      brandName:
        description: The brand name of the merchant.
        type: string
      comment:
        description: Notes or comments returned about the merchant.
        type: string
      descriptorText:
        description: Descriptor for the merchant provided by the Merchant Service Provider(MSP).
        type: string
      legalCorporateName:
        description: Corporate legal name of the merchant.
        type: string
      locationId:
        description: Merchant specific location identifier.
        format: int32
        type: integer
      matchConfidenceScore:
        description: Confidence score (%) to help clients understand the quality of the search results.
        format: int32
        type: integer
      merchantCategory:
        description: "Merchant category code and description associated with the merchant category code for the merchant. \r

          5814 - FAST FOOD RESTAURANTS, 5541 - SERVICE STATIONS WITH OR WITHOUT ANCILLARY SERVICE, \r

          5735 - RECORD SHOPS, 5971 - ART DEALERS AND GALLERIES"
        type: string
      merchantDbaName:
        description: Name under which the merchant is 'doing business as'.
        type: string
      phoneNumber:
        description: The phone number of the merchant.
        type: string
      soleProprietorName:
        description: ""
        type: string
    type: object
  MerchantIds:
    properties:
      message:
        description: Identifies the number of merchants found based on a request.
        type: string
      returnedMerchants:
        description: List of matching returned merchants
        items:
          $ref: "#/definitions/Merchant"
        type: array
        uniqueItems: false
    type: object
