# Merchant Search
## Search API Reference
- [Getting Started](https://developer.visa.com/capabilities/merchant_search/docs)
- [Authentication Method](https://developer.visa.com/capabilities/merchant_search/docs-authentication)
- [Error Codes](https://developer.visa.com/pages/visa-developer-error-codes)
- [Request and Response Codes](https://developer.visa.com/request_response_codes)
- [Frequently Asked Questions](https://developer.visa.com/capabilities/merchant_search/frequently-asked-questions)
- [Product Terms](https://developer.visa.com/capabilities/merchant_search/product-terms)
- [API Reference](#)
- Generic Search
- postGeneric Search API
- Nearby Merchants
- postMerchant Locator
- Transaction Enrichment
- postTransaction Lookup API
- postTransaction Search
## 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 <= 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
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
```json
{"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
```json
{"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"}}}
```