v1

latestSwagger 2.02026-07-1472831.8 KB
Merchant Locations

Returns merchant location information for merchants offering the following services: accept contactless-enabled cards and devices, allow customers to add money to an eligible MasterCard or Maestro prepaid card, issue MasterCard Prepaid Travel cards, participate in the MasterCard Easy Savings program, and offer cash at checkout when paying with a Debit MasterCard or Maestro Card.

Returns merchant location information for merchants offering the following services: accept contactless-enabled cards and devices, allow customers to add money to an eligible MasterCard or Maestro prepaid card, issue MasterCard Prepaid Travel cards, participate in the MasterCard Easy Savings program, and offer cash at checkout when paying with a Debit MasterCard or Maestro Card.

get/merchants/v1/merchant

Query parameters

Detailsstring required

Type of merchant location. Options are "acceptance.paypass" "topup.repower" "products.prepaidtravelcard" "offers.easysavings" and "features.cashback". Cash Back is currently only available in the US.

PageOffsetinteger required

Zero-based offset where the response will start. The actual start position is this value +1. An offset of 10 starts at item 11. Combined with the PageLength option this allows pagination to be supported through the service requests.

PageLengthinteger required

Maximum number of items to retrieve within the current "page" of results.

Categorystring

Category of the merchant location. See the Categories (Merchant) resource for a list of valid categories. This parameter is only valid for merchant queries with Details = "acceptance.paypass" or "features.cashback".

AddressLine1string

Line 1 of the street address for the merchant location. Usually includes the street number and name. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.

AddressLine2string

Line 2 of the street address usually an apartment number or suite number. This parameter is used rarely and is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.

Citystring

Name of the city for a merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.

CountrySubdivisionstring

State or province for a merchant location (only supported for US and Canada locations). This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.

PostalCodestring

Zip code or postal code for a merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.

Countrystring

Any three digit country code for an ATM location. Valid values are Three digit alpha country code as defined in ISO 3166-1. This parameter is ignored if latitude and longitude are provided. This parameter is required if any other address information is provided including AddressLine1 AddressLine2 City PostalCode or CountrySubdivision. By default we supply ATM location data for United States ATMs for up to twenty-five records per request.

Latitudenumber double

Latitude of a merchant location. If latitude is provided longitude must also be provided.

Longitudenumber double

Longitude of a merchant location. If longitude is provided latitude must also be provided.

DistanceUnitstring

Indicates the unit for the radius as well as the units of the distance of each location from the basepoint in the response.

Radiusinteger

This is the radius from the search point in the distance unit you set. For example if you want to search for locations within 50 miles of a certain point you would set DistanceUnit=mile and Radius=50. This parameter is ignored in non-geocoded countries.

OfferMerchantIDstring

Unique identifier that represents the merhcant sponsor of an offer. Any valid merchant ID.

Response

An array of Merchant locations

Example response

{
  "Merchants": {
    "Merchant": [
      {
        "Acceptance": {
          "PayPass": {
            "Concession": true,
            "DriveThru": true,
            "FuelPump": true,
            "Pharmacy": true,
            "Register": true,
            "Ticketing": true,
            "TollBooth": true,
            "VendingMachine": true
          }
        },
        "Category": "DINING AND ENTERTAINMENT",
        "Features": {
          "Cashback": {
            "MaximumAmount": 40
          }
        },
        "Location": {
          "Address": {
            "City": "CHICAGO",
            "Country": {
              "Code": "AFG",
              "Geocoding": true,
              "Name": "AFGHANISTAN"
            },
            "CountrySubdivision": {
              "Code": "IL",
              "Name": "ILLINOIS"
            },
            "Line1": "42 ELM AVENUE",
            "Line2": "SUITE 100"
          },
          "Distance": 0.91,
          "DistanceUnit": "KILOMETER",
          "LocationType": {
            "AirportCode": "JFK",
            "Type": "AIRPORT"
          },
          "Name": "QUIK TRIP STORE 1",
          "Point": {
            "Latitude": 32.75723000000001,
            "Longitude": 89.700215
          }
        },
        "Name": "MCDONALDS",
        "Products": {
          "PrepaidTravelcard": true
        },
        "Topup": {
          "rePower": {
            "CardSwipe": true,
            "MoneyPak": true
          }
        },
        "WebsiteUrl": "www.mcdonalds.com"
      }
    ],
    "TotalCount": 86
  }
}