# 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.

## Merchant Match Test Cases {#merchant-match-test-cases}

### Positive Test Cases {#positive-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"
    }
]
```

**Validate:**

* HTTP status is `200 OK`
* Response is a JSON array
* `locationId` is a non-empty UUID
* `matchRank` is `1`
* `countryCode` matches the requested `country_code`
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

```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"
    }
]
```

**Validate:**

* HTTP status is `200 OK`
* Response is a JSON array with exactly one match
* `merchantName` matches the requested `company_name`
* `locationId` is a non-empty UUID

<br />

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": "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"
    }
]
```

**Validate:**

* HTTP status is `200 OK`
* Response is a JSON array with up to 3 matches
* Matches are ordered by `matchRank` (1, 2, 3)
* Each match contains a unique `locationId`

### Negative Test Cases {#negative-test-cases}

Test Data

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

|    Parameter Name     |       Value       |
|-----------------------|-------------------|
| company_name          | Handcrafted Haven |
| street_address        | 2002 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."
          }
      ]
  }
}
```

**Validate:**

* HTTP status is `404`
* Response contains `Errors.Error[]` array
* `ReasonCode` is `MATCHES_NOT_FOUND`
* `Recoverable` is `false`

Fo