Merchant Search API Reference

Merchant Search

Search API Reference

Generic Search

Generic Search API is used to Search for Visa accepting merchants with general merchant parameters such as name, location etc. The typical use case for this API includes identifying Visa-accepting suppliers, onboarding merchants for rewards programs etc.

Generic Search API v2 - Latest v1 v2 - Latest

Use general merchant parameters to retrieve merchant information from Visa’s global merchant repository

Request

Request Body schema: application/json
header object
--- ---
messageDateTime
required		 string YYYY-MM-DDThh:mm:ss.sss <= 23 characters
Date and time at which Request is sent (up to milliseconds in UTC). Ex: 2008-09-19T00:00:00.000
Example: "2017-05-19T22:05:00.000"
requestMessageId
required		 string <= 50 characters
A string which uniquely identifies the service request. Requesting application need to create this unique message ID
Example: "RequestMessgeId123"
startIndex string <Default='0'>
Records displayed in Response start at the specified number (Defaulted to 0 if not provided in request)
Example: "0"
responseAttrList Array of strings non-empty
A group name is assigned by Visa for clients during onboarding. By default, most clients are assigned a group name
Example: ["GNSTANDARD3"]
searchAttrList object
--- ---
acquirerCardAcceptorId string
CAID - Acquirer Card Acceptor ID. Note: CAID and Acquirer MID tends to be the same in many cases. However, the value seen in transactions is CAID
Example: "412345-12000"
acquirerMid string
Acquirer assigned Merchant ID (MID) value. Note: This field is different from Visa's internal VMID value
Example: "1-abc-3456"
acquiringBin string
Acquirer BIN of merchant (if available)
Example: "412345"
cashBackIndicator string
Indicates if the merchant store offers cash back. Applicable values: Y or N
Example: "Y"
firstTranDateRange string
A flag which indicates the first transaction date range of the merchant. Applicable values: In last 30 days, In last 90 days, In last 180 days, In last 365 days, In more that 365 days
Example: "IN LAST 30 DAYS"
lastTranDateRange string
A flag which indicates the last transaction date range of the merchant. Applicable values: In last 30 days, In last 90 days, In last 180 days, In last 365 days, In more that 365 days
Example: "IN LAST 90 DAYS"
merchantCategoryCode Array of strings
Merchant category code (MCC) value used by merchant in transactions
Example: ["4111"]
merchantCity string
City of the merchant location
Example: "SAN JOSE"
merchantCountryCode string
Country code of the merchant location. Note: Kindly use the 3 digit ISO standard value of country code
Example: "840"
merchantName string
The name of the merchant
Example: "ABC BUSINESS"
merchantPhoneNumber string
Phone number of the Merchant
Example: "8881234567"
merchantPostalCode string
Postal code of the merchant location
Example: "12345"
merchantState string
State of the merchant location
Example: "CA"
merchantStreetAddress string
Street Address of the registered Merchant
Example: "123 main street"
merchantUrl string
URL of the Merchant
Example: "www.abc.com"
paymentAcceptanceMethod string
Indicates the payment acceptance method available at the merchant.Applicable values: F2F (Face to face), EC (E-commerce), MOTO (Mail order Telephone Order)
Example: "F2F"
terminalType string
The type of terminal available at the merchant. Applicable values: Swipe, Chip, Paywave (contactless)
Example: "SWIPE"
visaEnterpriseId string
VEID - Visa's identifier for a merchant at an enterprise level. Note: This value is internal to Visa and is only applicable if you already have obtained this through Merchant Search.
Example: "80000001"
visaMerchantId string
VMID - Visa's identifier for merchant at a brand level. Note: This value is internal to Visa and is only applicable if you already have obtained this through Merchant Search.
Example: "11111111"
visaStoreId string
VSID - Visa's unique identifier of a merchant store location. Note: This value is internal to Visa and is only applicable if you already have obtained this through Merchant Search
Example: "270000111"
searchOptions object
--- ---
confidenceScores boolean
Allows to view the confidence score value of response
Example: false
matchIndicators boolean
Provides indicators in response to show which data attributes matched
Example: true
matchScore boolean
Allows to see the match score value. Note: Match score is used to rank responses. The absolute value of match score is not an indication of quality of response. Use confidence score to evaluate quality of response.
Example: true
maxRecords string
Maximum number of records to be displayed in the response if there are multiple matches. Use 1 if looking for only the top result. If you prefer to view other possible matches, use 5 or 10
Example: "5"
searchType string
Possible values - 'Search', 'ExploratorySearch'. Use 'Search' as the default option. 'ExploratorySearch' provides slightly elaborate search results
Example: "Search"
similarityScores boolean
Allows to view the similarity score values for merchant name and street address in response
Example: true

Responses

200 Successful Response

Response Schema: application/json
header object
--- ---
endIndex string
The end index number
Example: "2"
messageDateTime string
Date and time at which Response is sent (up to milliseconds in UTC).
Example: "2008-09-19T00:00:00.000"
numRecordsMatched string
Provides an indication of number of records matched. If there is only a single match, it will return the value 1. In certain cases when there are multiple matches, this field indicates the number of matches and would be ranked by the match score.
Example: "5"
numRecordsReturned string
In cases where there are multiple responses, the number of records returned will be limited by 'maxrecords' field in request. For example, if there are 3 matches and 'maxrecords' has a value of 2, number of records returned would be 2.
Example: "2"
requestMessageId string
A string uniquely identifies the service response.
Example: ""
responseMessageId string
A string uniquely identifies the service request. Response will contain same Message Id as received from requesting application
Example: ""
startIndex string
The start index number
Example: "5"
response object
--- ---
matchIndicators
required		 object
List of attributes that found a match or did not find a match
--- ---
acquirerCardAcceptorId string
Whether field is matched, Y/N
Example: "Y"
acquiringBin string
Whether field is matched, Y/N
Example: "Y"
merchantCategoryCode string
Whether field is matched, Y/N
Example: "Y"
merchantCity string
Whether field is matched, Y/N
Example: "Y"
merchantCountryCode string
Whether field is matched, Y/N
Example: "Y"
merchantName string
Whether field is matched, Y/N
Example: "Y"
merchantPostalCode string
Whether field is matched, Y/N
Example: "Y"
merchantState string
Whether field is matched, Y/N
Example: "Y"
matchScore
required		 number
Match Score for the record. Note: Match score is used to rank responses. The absolute value of match score is not an indication of quality of response. Use confidence score to evaluate quality of response
Example: 44.927692
responseValues
required		 object
--- ---
brandName string
Brand/trademark name of the merchant
Example: "Abc's Coffee"
businessLegalName string
Business legal name of the merchant
Example: "XYZ Inc."
cardNotPresentVsid string
Indicates whether the Visa Store ID value is only for card not present - Y/N
Example: "Y"
cashBackIndicator string
Indicates if the merchant store offers cash back
Example: "Y"
categoryIconUrl string
A category icon image corresponding to the field 'primaryMerchantCategoryGroup'
Example: "https://images.visa.com/GMR/logos/0813/Xyjhjhgd787Uud.png"
dbaname string
Doing business as name
Example: "ABC STORE"
firstTranDateRange string
A flag which indicates the first transaction date range of the merchant. Applicable values: In last 30 days, In last 90 days, In last 180 days, In last 365 days, In more that 365 days
Example: "IN LAST 30 DAYS"
lastTranDateRange string
A flag which indicates the last transaction date range of the merchant. Applicable values: In last 30 days, In last 90 days, In last 180 days, In last 365 days, In more that 365 days
Example: "IN LAST 30 DAYS"
locationAddressLatitude string
The latitude co-ordinates of the merchant store location
Example: "37.7661"
locationAddressLongitude string
The longitude co-ordinates of merchant store location
Example: "-122.3958"
merchantCategoryCode Array of strings
The various merchant category codes used by the merchant at it's store location
Example: ["5812"]
merchantCategoryCodeDesc Array of strings
Eating Places and Restaurants
Example: ["5812"]
merchantCity string
The city of the merchant store location
Example: "SAN JOSE"
merchantCountryCode string
The country code of the merchant store location
Example: "840"
merchantIconUrl string
Brand logo icon of the merchant. Note: 'merchantIconUrl' is better suited for a square surface, while 'merchantLogoUrl' is more appropriate for a horizontal one.
Example: "https://images.visa.com/GMR/icons/7521/XbbPtRRU9AKUOg.jpeg"
merchantLogoUrl string
Brand logos of the merchant. Note: 'merchantIconUrl' is better suited for a square surface, while 'merchantLogoUrl' is more appropriate for a horizontal one.
Example: "https://images.visa.com/GMR/logos/0813/8R8xVR9UkizA.png"
merchantPhoneNumber object
Phone number of merchant store location and it's type
--- ---
number string
Number
type string
Type
merchantPostalCode string
The postal code of the merchant store location
Example: "12345"
merchantPrimaryUrl string
The primary URL of the merchant
Example: "WWW.ABC.COM"
merchantState string
The state of the merchant store location
Example: "CA"
merchantStreetAddress string
Street Address of the registered Merchant
Example: "123 MAIN STREET"
merchantUrl Array of strings
URLs of merchant website if available
Example: ["WWW.ABC.COM"]
paymentAcceptanceMethod Array of strings
Indicates the payment acceptance method available at the merchant.Applicable values: F2F (Face to face), EC (E-commerce), MOTO (Mail order Telephone Order)
Example: ["F2F"]
paymentFacilitatorName string
The name of the payment facilitator used by the merchant (if applicable)
Example: "PAYPAL"
primaryMerchantCategoryCode string
The primary merchant category code of merchant
Example: "5812"
primaryMerchantCategoryGroup string
The primary merchant category group of the merchant. Currently merchants are classified into 28 different category groups.
Example: "Restaurant"
primaryPhoneNumber string
The primary phone number of the merchant
Example: "8001234567"
spMrchFlag string
A flag which indicates whether the merchant is sponsored by a payment facilitator (if applicable)
Example: "Y"
terminalType Array of strings
Indicates the type of terminal available at the merchant.Applicable values: Swipe, Chip, Paywave (contactless)
Example: ["SWIPE"]
visaEnterpriseId string
The identifier for a merchant at an enterprise level (VEID). VEIDs can have multiple VMIDs associated with it. For example Yum Brands which owns Pizza Hut (VMID) will have a VEID and it can have multiple brands (VMIDs) under it.
Example: "4111"
visaEnterpriseName string
The name of merchant's parent enterprise.
Example: "134567"
visaMerchantId string
The identifier for merchant at a brand level. For example, Pizza Hut would be a brand and the Visa Merchant ID (VMID - 1111111) can be used to identify the merchant brand. One VMID can have multiple VSIDs. E.g. Pizza Hut (VMID) has multiple stores (VSIDs) in different cities.
Example: "11111111"
visaMerchantName string
VMID - The name of merchant at a brand level
Example: "ABC BUSINESS"
visaStoreId string
The unique identifier of a merchant store location. For example, a Pizza Hut restaurant at 123 Main street, San Mateo, California would have a unique Visa store ID (VSID)
Example: "123456789"
visaStoreName string
The name of merchant at store location
Example: "Pizza Hut, San Mateo"
status object
--- ---
statusCode
required		 string
Status Code of the Service Request
statusDescription
required		 string
A description of the StatusCode. A brief description indicating the result of the Service request

Sample Request

{"searchOptions": {"matchScore": "true",

"maxRecords": "5",

"matchIndicators": "true",

"searchType": "Search",

"confidenceScores": "true"},

"header": {"startIndex": "0",

"requestMessageId": "VCO_GMR_001",

"messageDateTime": "2015-08-28T22:05:00.000"},

"searchAttrList": {"merchantPhoneNumber": "4153440351",

"merchantCity": "San Francisco",

"merchantCountryCode": "840",

"merchantPostalCode": "94107",

"merchantStreetAddress": "280 King St",

"merchantState": "CA",

"merchantName": "Starbucks "},

"responseAttrList": ["GNSTANDARD3"]
}

Sample Response

{"merchantSearchServiceResponse": {"response": [{"matchScore": 154.00719,

"confidenceScore": 0.04706260480879823,

"matchIndicators": {"merchantPhoneNumber": "Y",

"merchantCity": "Y",

"merchantCountryCode": "Y",

"merchantPostalCode": "Y",

"merchantStreetAddress": "Y",

"merchantState": "Y",

"merchantName": "Y"},

"responseValues": {"visaEnterpriseName": "STARBUCKS CORPORATION",

"merchantPhoneNumber": [{"number": "+1 (800) 782-7282",

"type": "C"},

{"number": "30091532",

"type": "O"},

{"number": "(415) 344-0351",

"type": "O"},

{"number": "4153440351",

"type": "O"}],

"addressSimilarityScore": "1.0",

"primaryMerchantCategoryGroup": "Quick Service Restaurants",

"merchantCountryCode": "840",

"merchantIconUrl": "https://cdn-images.visa.com/GMR/icons/7927/NRL23jJgJfy4Cw.jpeg",

"visaEnterpriseId": "70336582810",

"paymentAcceptanceMethod": ["F2F"],

"locationAddressLongitude": "-122.393597",

"merchantCategoryCodeDesc": ["FAST FOOD RESTAURANTS"],

"firstTranDateRange": "IN MORE THAN 365 DAYS",

"merchantState": "CA",

"merchantPrimaryUrl": "WWW.STARBUCKS.COM",

"visaStoreName": "STARBUCKS",

"locationAddressLatitude": "37.777019",

"merchantPostalCode": "94107-1702",

"visaStoreId": "685334850",

"dbaname": ["Starbucks Store 06677"],

"categoryIconUrl": "",

"merchantLogoUrl": "https://cdn-images.visa.com/GMR/logos/7927/UdjVxC68aOHJsA.png",

"visaMerchantName": "STARBUCKS",

"brandName": "Starbucks",

"lastTranDateRange": "IN MORE THAN 365 DAYS",

"merchantCity": "SAN FRANCISCO",

"spMrchFlag": "",

"primaryPhoneNumber": "+1 (800) 782-7282",

"terminalType": ["SWIPE","CHIP","PAYWAVE"],

"visaMerchantId": "29992901",

"primaryMerchantCategoryCode": "5814",

"merchantCategoryCode": ["5814"],

"businessLegalName": ["Starbucks Corporation"],

"merchantStreetAddress": "280 KING ST",

"paymentFacilitatorName": [],

"merchantUrl": ["WWW.STARBUCKS.COM","STARBUCKS.COM"]},

"confidenceRange": "LOW"}],

"header": {"numRecordsReturned": 1,

"startIndex": "0",

"numRecordsMatched": 104,

"responseMessageId": "6a4a69a5-52cd-4b54-8bda-f7e29bb3a1e0",

"endIndex": "0",

"requestMessageId": "VCO_GMR_001",

"messageDateTime": "2025-02-19T23:25:04.004"},

"status": {"statusDescription": "Success",

"statusCode": "CDI000"}}}