# Merchant Match
source: https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/merchant-match/index.md

## Introduction {#introduction}

The end-point allows the client to retrieve location details of the top 3 matches from Mastercard.  

**Note**: It is recommended to use merchant match using ID type and ID value for better accuracy. In case of merchant match using Name and Address, verify that city and country combinations are valid. Certain parameters, such as state_province_region and postal_code may vary or may not be required for some regions. For e.g, in Brazil both "Rio de Janeiro" or "RJ" are accepted.

## Test Cases {#test-cases}


Test Data

Below you may find the query parameters associated with this test case.

| Parameter Name |    Value     |
|----------------|--------------|
| country_code   | USA          |
| id_type        | MERCHANT_ID  |
| id_value       | 106241230D01 |

Request

```python
{
    "country_code": "USA",
    "id_type": "MERCHANT_ID",
    "id_value": "106241230D01"
}
```

Response

```json
[
    {
        "locationId": "a1b2c3d4-0000-1234-abcd-000000000001",
        "matchRank": 1,
        "merchantName": "Artisan Emporium",
        "streetAddress": "2000 Purchase St",
        "city": "Purchase",
        "state": "NY",
        "postalCode": "10577",
        "countryCode": "USA"
    }
]
```

Test Data

Below you may find the query parameters associated with this test case.  
Request

```python
{
    "company_name": "Artisan Emporium",
    "street_address": "2000 Purchase St",
    "city": "Purchase",
    "state_province_region": "NY",
    "postal_code": "10577",
    "country_code": "USA"
}
```

Response

```json
[
    {
        "locationId": "a1b2c3d4-0000-1234-abcd-000000000001",
        "matchRank": 1,
        "merchantName": "Artisan Emporium",
        "streetAddress": "2000 Purchase St",
        "city": "Purchase",
        "state": "NY",
        "postalCode": "10577",
        "countryCode": "USA"
    }
]
```

<br />

Test Data

Below you may find the query parameters associated with this test case.  

|    Parameter Name     |      Value       |
|-----------------------|------------------|
| company_name          | Artisan Emporium |
| street_address        | 2000 Purchase St |
| city                  | Purchase         |
| state_province_region | NY               |
| postal_code           | 10577            |
| country_code          | USA              |

Request

```json
{
    "company_name": "Creative Collective",
    "street_address": "2001 Purchase St",
    "city": "Purchase",
    "state_province_region": "NY",
    "postal_code": "10577",
    "country_code": "USA"
}
```

Response

```json
[
    {
        "locationId": "a1b2c3d4-0000-1234-abcd-000000000002",
        "matchRank": 1,
        "merchantName": "Creative Collective",
        "streetAddress": "2001 Purchase St",
        "city": "Purchase",
        "state": "NY",
        "postalCode": "10577",
        "countryCode": "USA"
    },
    {
        "locationId": "a1b2c3d4-0000-1234-abcd-000000000003",
        "matchRank": 2,
        "merchantName": "Creative Collective Ltd",
        "streetAddress": "2010 Purchase St",
        "city": "Purchase",
        "state": "NY",
        "postalCode": "10577-1402",
        "countryCode": "USA"
    },
    {
        "locationId": "a1b2c3d4-0000-1234-abcd-000000000004",
        "matchRank": 3,
        "merchantName": "Maker Central",
        "streetAddress": "100 Manhattanville Rd",
        "city": "Purchase",
        "state": "NY",
        "postalCode": "10578",
        "countryCode": "USA"
    }
]
```

Test Data

Below you may find the query parameters associated with this test case.  

|    Parameter Name     |        Value        |
|-----------------------|---------------------|
| company_name          | Creative Collective |
| street_address        | 2001 Purchase St    |
| city                  | Purchase            |
| state_province_region | NY                  |
| postal_code           | 10577               |
| country_code          | USA                 |

Request

```json
{
    "company_name": "Handcrafted Haven",
    "street_address": "2002 Purchase St",
    "city": "Purchase",
    "state_province_region": "NY",
    "postal_code": "10577",
    "country_code": "USA"
}
```

Response

```json

{
  "Errors": {
      "Error": [
          {
              "Source": "CreditAnalytics",
              "ReasonCode": "MATCHES_NOT_FOUND",
              "Description": "No potential matches found",
              "Recoverable": false,
              "Details": "Check with the merchant for alternative values for the company name, address, and other similar values."
          }
      ]
  }
}
```

|    Parameter Name     |       Value       |
|-----------------------|-------------------|
| company_name          | Handcrafted Haven |
| street_address        | 2002 Purchase St  |
| city                  | Purchase          |
| state_province_region | NY                |
| postal_code           | 10577             |
| country_code          | USA               |