# 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 matching with ID type and ID value for greater accuracy. When using merchant matching based on Name and Address, verify that the city and country combinations are valid. Certain parameters, such as state_province_region and postal_code, may vary by region or may not be required in some regions. For example, in Brazil both "Rio de Janeiro" and "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

```json
{
    "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

```json
{
    "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`

## Next Steps {#next-steps}

* [Merchant Metrics](https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/merchant-metrics/index.md) --- continue with the next step of the end-to-end flow
* [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md#matches-errors) --- full list of `/matches` error codes
* [Use Cases](https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/index.md) --- business scenarios that use this endpoint