# Testing
source: https://developer.mastercard.com/match/documentation/testing/index.md

## Overview {#overview}

Use this page to plan and execute Sandbox validation for the MATCH Pro API. It covers the recommended workflow, positive and negative coverage, and the reference guides you need for endpoint-level execution.
Tip: Start all validation in **Sandbox** before moving to MTF and Production. Sandbox URL: `https://sandbox.apiedge.mastercard.com/mcp/match/api` Note: See the [Quick Start Guide](https://developer.mastercard.com/match/documentation/quick-start-guide/index.md) to check on the multiple ways to integrate with the MATCH Pro API.

## Test Environments {#test-environments}

| Environment |                                                                             Purpose                                                                             |                        Base URL                        |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| Sandbox     | Public, self-service environment with mocked responses to validate connectivity, OAuth signing, and request/response handling. No Mastercard approval required. | `https://sandbox.apiedge.mastercard.com/mcp/match/api` |
| MTF         | Controlled environment for full user acceptance testing (UAT) with test data. Requires **Request MTF Access** from your project.                                | `https://apiedge.mastercard.com/mtf/mcp/match/api`     |
| Production  | Live services. Requires **Request Production Access** and approval.                                                                                             | `https://apiedge.mastercard.com/mcp/match/api`         |

## Choose a testing method {#choose-a-testing-method}

Choose a testing method that best matches how you want to validate requests:

* **[Postman Collection](https://developer.mastercard.com/match/documentation/developer-tools/postman-collection/index.md)** --- an API client that allows developers to test API calls in Sandbox and Production environments without writing any code.
* **[Reference Application](https://developer.mastercard.com/match/documentation/developer-tools/reference-app/index.md)** --- a working implementation that allows you to integrate the different operations.

## Recommended testing flow {#recommended-testing-flow}

Validate the MATCH Pro operations with the following apis:

1. Add Terminated Merchant
2. Termination Inquiry
3. New Merchant Insights
4. Termination Inquiry History
5. Merchant Performance Indicators
6. Retroactive Inquiry List
7. Retroactive Inquiry Details
8. Acquirer Contact
9. Countries
10. States
11. Cities

## Required Parameters {#required-parameters}

For some API calls, one or more parameters might be needed in the URI while sending the request (for example, `inquiry_ref_num`). Check below where these parameters can be extracted from:

|     Parameter     |                                                                                                                                                                                                                                 Resources used to retrieve parameter                                                                                                                                                                                                                                  |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inquiry_ref_num` | [Termination Inquiry](https://developer.mastercard.com/match/documentation/testing/index.md#2-termination-inquiry) (`POST /termination-inquiries`) returns an Inquiry Reference Number that can be used in Termination Inquiry History and New Merchant Insights. [Retroactive Inquiry List](https://developer.mastercard.com/match/documentation/testing/index.md#6-retroactive-inquiry-list) (`POST /retros/retro-lists`) returns Inquiry Reference Numbers for use in Retroactive Inquiry Details. |
| `country_code`    | [Countries](https://developer.mastercard.com/match/documentation/testing/index.md#9-countries) (`GET /countries`) can be used to retrieve a valid 3-letter ISO `country_code`.                                                                                                                                                                                                                                                                                                                        |
| `state_code`      | [States](https://developer.mastercard.com/match/documentation/testing/index.md#10-states) (`GET /countries/{country_code}/states`) can be used to retrieve a valid state/province code.                                                                                                                                                                                                                                                                                                               |
| `acquirerId`      | Provided to your project during onboarding. The Sandbox uses a single acquirer ICA (**1996**).                                                                                                                                                                                                                                                                                                                                                                                                        |

Note: See the [API Reference](https://developer.mastercard.com/match/documentation/api-reference/index.md) for detailed info on each API call, request schema, and response structure.

## Positive testing {#positive-testing}

Positive testing confirms that valid requests succeed and return the expected data.

**Validate these behaviors**

* Valid request bodies return success codes, such as `200 OK`.
* Created resources (for example, a terminated merchant) can be retrieved by their Inquiry Reference Number or found through search.
* Submitted inquiries persist and can be verified with a follow-up `GET` using the Inquiry Reference Number.
* Search and filter parameters (such as `pageLength` and `pageOffset`) return the expected subset of records.

### 1. Add Terminated Merchant {#1-add-terminated-merchant}

|        API Call         |                        Description                        |               URI               |   Response   |
|-------------------------|-----------------------------------------------------------|---------------------------------|--------------|
| Add Terminated Merchant | Adds a new terminated merchant to the MATCH Pro database. | `POST /merchants/add-merchants` | HTTP: 200 OK |

```json
{
  "addMerchantRequest": {
    "acquirerId": "1996",
    "merchant": {
      "isProprietorship": "N",
      "name": "THE BAIT SHOP",
      "merchantId": "ABED-1234",
      "address": {
        "addressLineOne": "42 ELM AVENUE",
        "city": "Fayzabad",
        "country": "AFG",
        "isOtherCity": "N",
        "postalCode": "66579"
      },
      "phoneNumber": "6367558963",
      "merchantCategory": "0742",
      "dateOpened": "2021-07-14",
      "dateClosed": "2021-07-14",
      "reasonCode": "04",
      "isTransactionLaundering": "N",
      "principals": [
        {
          "firstName": "JACK",
          "lastName": "SMITH",
          "address": {
            "addressLineOne": "42 ELM AVENUE",
            "city": "Fayzabad",
            "country": "AFG",
            "isOtherCity": "N",
            "postalCode": "66579"
          },
          "phoneNumber": "6360000000",
          "email": "JACK_SMITH@XYZ.COM",
          "dateOfBirth": "1980-01-01"
        }
      ]
    }
  }
}
```

```json
{
  "addMerchantResponse": {
    "merchantReferenceNumber": "1996-250812084304-KJMLJ4I0",
    "name": "THE BAIT SHOP"
  }
}
```

### 2. Termination Inquiry {#2-termination-inquiry}

|          API Call          |                                                Description                                                |              URI              |   Response   |
|----------------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------|--------------|
| Create Termination Inquiry | Retrieves terminated merchant information and New Merchant Insights based on the criteria in the request. | `POST /termination-inquiries` | HTTP: 200 OK |

```json
{
  "terminationInquiryRequest": {
    "acquirerId": "1996",
    "merchant": {
      "name": "THE BAIT SHOP",
      "doingBusinessAsName": "BAIT R US",
      "address": {
        "addressLineOne": "42 ELM AVENUE",
        "city": "Fayzabad",
        "country": "AFG",
        "isOtherCity": "N",
        "postalCode": "66579"
      },
      "phoneNumber": "6367558963",
      "merchantCategory": "0742",
      "urls": [ "www.merchant.com" ],
      "principals": [
        {
          "firstName": "JACK",
          "lastName": "SMITH",
          "phoneNumber": "6360000000",
          "email": "JACK_SMITH@XYZ.COM"
        }
      ]
    }
  }
}
```

```json
{
  "terminationInquiryResponse": {
    "pageOffset": 0,
    "ref": "1996-250516085206-J9ZHK5KT",
    "possibleMerchantMatches": [
      {
        "totalMerchantMatches": 1,
        "terminatedMerchants": [
          {
            "merchant": {
              "name": "THE BAIT SHOP",
              "doingBusinessAsName": "BAIT R US",
              "phoneNumber": "6367558963",
              "merchantCategory": "0742",
              "address": {
                "addressLineOne": "42 ELM AVENUE",
                "city": "Fayzabad",
                "country": "AFG",
                "postalCode": "66579"
              },
              "principals": [
                {
                  "firstName": "JACK",
                  "lastName": "SMITH",
                  "phoneNumber": "6360000000",
                  "email": "JACK_SMITH@XYZ.COM"
                }
              ]
            },
            "merchantMatch": {
              "name": "M01",
              "doingBusinessAsName": "M01",
              "phoneNumber": "M01",
              "address": "M01"
            }
          }
        ]
      }
    ]
  }
}
```

### 3. New Merchant Insights {#3-new-merchant-insights}

|            API Call            |                                                              Description                                                               |                           URI                            |   Response   |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------|
| Retrieve New Merchant Insights | Retrieves the merchant risk score and fraud risk signals using the Inquiry Reference Number (IRN) returned from a termination inquiry. | `GET /merchants/new-merchant-insights/{inquiry_ref_num}` | HTTP: 200 OK |

```text
GET /merchants/new-merchant-insights/1996-250516085206-J9ZHK5KT
```

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "inquiryRefNumber": "1996-250516085206-J9ZHK5KT",
  "insightId": "6b018553-96eb-46f1-b45f-72e165512544",
  "merchantRiskScore": {
    "score": 0.351,
    "reasonCode": "LF, LE, LI",
    "reasonDescription": "LF - Low Inquiry Attribute Consistency Risk, LE - Low Inquiry Attribute Completeness Risk, LI - Low Inquiry Attribute Volatility Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": null,
      "sameMerchantLocationPrincipalLocation": null,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 0,
      "numPerMerchantPrincipalPair": 1,
      "numPerMerchantPhone": null,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": null,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": true,
      "entityFirstSeenDays": 197,
      "entityLastSeenDays": 3,
      "entityMCCCount": 1,
      "entityMerchantCount": 1,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "low",
      "negativeReviewPresence": "low",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 71,
      "hasHijackingProtection": false,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 2,
      "hasMinimalContent": false,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": false
    }
  },
  "assessmentStatus": "COMPLETED",
  "assessmentTimestamp": "2026-06-29T07:20:50.52Z",
  "warnings": []
}
```

### 4. Termination Inquiry History {#4-termination-inquiry-history}

|               API Call               |                                        Description                                         |                      URI                       |   Response   |
|--------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------|--------------|
| Retrieve Termination Inquiry History | Retrieves historical termination inquiry results using the Inquiry Reference Number (IRN). | `GET /termination-inquiries/{inquiry_ref_num}` | HTTP: 200 OK |

```text
GET /termination-inquiries/1996-250516085206-J9ZHK5KT
```

```json
{
  "terminationInquiryHistory": {
    "terminationInquiryRequest": {
      "acquirerId": "1996",
      "merchant": {
        "name": "THE BAIT SHOP",
        "phoneNumber": "6367558963",
        "merchantCategory": "0742",
        "address": {
          "addressLineOne": "42 ELM AVENUE",
          "city": "Fayzabad",
          "country": "AFG",
          "postalCode": "66579"
        }
      }
    },
    "terminationInquiryResponse": {
      "pageOffset": 0,
      "ref": "1996-250516085206-J9ZHK5KT",
      "possibleMerchantMatches": [
        {
          "totalMerchantMatches": 1,
          "terminatedMerchants": [
            {
              "merchant": {
                "name": "THE BAIT SHOP",
                "merchantCategory": "0742"
              },
              "merchantMatch": {
                "name": "M01",
                "phoneNumber": "M01"
              }
            }
          ]
        }
      ]
    }
  }
}
```

### 5. Merchant Performance Indicators {#5-merchant-performance-indicators}

|                 API Call                 |                                                                         Description                                                                         |                   URI                    |   Response   |
|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|--------------|
| Retrieve Merchant Performance Indicators | Returns aggregated performance metrics (GDV, approval rate, chargeback, fraud) by National Tax ID. Available to Brazil acquirers subscribed to the service. | `POST /merchants/performance-indicators` | HTTP: 200 OK |

```json
{
  "acquirerId": "1996",
  "criteria": [
    { "field": "NATIONALTAXID", "value": "NT_123456789/01" }
  ],
  "betweenCriteria": [
    { "field": "PI_DATE", "operator": "BETWEEN", "from": "2026-01", "to": "2026-03" }
  ]
}
```

```json
{
  "noOfAcquirer": 3,
  "merchants": [
    {
      "firstTransactionDate": "2023-01-01",
      "merchantName": "THE BAIT SHOP",
      "businessType": "RETAIL OPERATING COMPANY",
      "recommendedMcc": "5814",
      "recommendedMccDataSource": "CNPJ",
      "recommendedMccDescription": "GIFT SHOP",
      "additionalFields": [
        { "field": "BUSINESS STATUS", "value": "ACTIVE" }
      ]
    }
  ],
  "performance": {
    "categoryDefinitions": [
      { "code": "cp", "label": "Card Present" },
      { "code": "cnp", "label": "Card Not Present" },
      { "code": "total", "label": "Overall" }
    ],
    "indicatorDefinitions": [
      {
        "type": "GROSS_DOMESTIC_VOLUME",
        "intervalUnit": "PERCENT",
        "intervalType": "Monthly",
        "recommendedChart": "BAR",
        "isParent": true,
        "childIndicators": [ "APPROVAL_RATE" ]
      },
      {
        "type": "FRAUD",
        "intervalUnit": "BASIS_POINTS",
        "intervalType": "Monthly",
        "recommendedChart": "LINE",
        "isParent": false,
        "childIndicators": []
      }
    ],
    "indicators": [
      {
        "type": "GROSS_DOMESTIC_VOLUME",
        "categories": [
          {
            "code": "total",
            "summary": {
              "min": 980000.0,
              "minMonth": "2026-01",
              "max": 1250000.0,
              "maxMonth": "2026-03",
              "avg": 1115000.0
            },
            "intervalMetrics": [
              { "interval": "2026-01", "value": 980000.0 },
              { "interval": "2026-02", "value": 1115000.0 },
              { "interval": "2026-03", "value": 1250000.0 }
            ]
          }
        ]
      }
    ],
    "compliances": [
      {
        "programName": "BRAM",
        "previousState": "Non-Compliant",
        "currentState": "Compliant",
        "previousReferenceNumber": "CASE-1234",
        "currentReferenceNumber": "CASE-5678",
        "additionalFields": [
          { "field": "BUSINESS STATUS", "value": "ACTIVE" }
        ]
      }
    ]
  },
  "merchantInquiryTerminationStats": {
    "inquiryStat": {
      "totalInquiries": 123,
      "intervalType": "Monthly",
      "intervalMetrics": [
        { "interval": "2026-01", "value": 40.0 },
        { "interval": "2026-02", "value": 41.0 },
        { "interval": "2026-03", "value": 42.0 }
      ]
    },
    "merchantTerminationStats": [
      {
        "count": 1,
        "reason": "04 - EXCESSIVE CHARGEBACKS",
        "dateTerminated": "2025-09-24"
      }
    ]
  }
}
```

### 6. Retroactive Inquiry List {#6-retroactive-inquiry-list}

|            API Call            |                                          Description                                          |            URI             |   Response   |
|--------------------------------|-----------------------------------------------------------------------------------------------|----------------------------|--------------|
| Retrieve Retroactive Inquiries | Retrieves the list of termination inquiry matches made within 360 days of inquiry initiation. | `POST /retros/retro-lists` | HTTP: 200 OK |

```json
{
  "retroInquiryRequest": {
    "acquirerId": "1996"
  }
}
```

```json
{
  "retroResponse": {
    "totalRetroInquiries": 1,
    "retroInquiries": [
      {
        "inquiryRefNum": "1996220406041727K485",
        "merchantName": "THE BAIT SHOP",
        "city": "Fayzabad",
        "state": "BDS",
        "country": "AFG",
        "createdDate": "2021-07-14",
        "inquiryCreatedDate": "2021-07-14",
        "acquirerId": "1996"
      }
    ]
  }
}
```

### 7. Retroactive Inquiry Details {#7-retroactive-inquiry-details}

|               API Call               |                                              Description                                               |                          URI                          |   Response   |
|--------------------------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------|--------------|
| Retrieve Retroactive Inquiry Details | Retrieves the detailed match information for a retroactive inquiry using its Inquiry Reference Number. | `GET /retros/retro-inquiry-details/{inquiry_ref_num}` | HTTP: 200 OK |

```text
GET /retros/retro-inquiry-details/1996-220406041727-K485ZQ9T
```

```json
{
  "retroInquiryResponse": {
    "possibleMerchantMatches": [
      {
        "totalMerchantMatches": 1,
        "terminatedMerchants": [
          {
            "merchant": {
              "name": "THE BAIT SHOP",
              "doingBusinessAsName": "BAIT R US",
              "phoneNumber": "6367558963",
              "merchantCategory": "0742",
              "address": {
                "addressLineOne": "42 ELM AVENUE",
                "city": "Fayzabad",
                "country": "AFG",
                "postalCode": "66579"
              }
            },
            "merchantMatch": {
              "name": "M01",
              "phoneNumber": "M01",
              "address": "M01"
            }
          }
        ]
      }
    ]
  }
}
```

### 8. Acquirer Contact {#8-acquirer-contact}

|         API Call          |                          Description                           |           URI           |   Response   |
|---------------------------|----------------------------------------------------------------|-------------------------|--------------|
| Retrieve Acquirer Contact | Returns the contact information for the requested acquirer ID. | `POST /contact-details` | HTTP: 200 OK |

```json
{
  "contactRequest": {
    "acquirerId": "12086"
  }
}
```

```json
{
  "contactDetails": [
    {
      "bankName": "THE XYZ BANK",
      "region": "UNITED STATES",
      "firstName": "JACK",
      "lastName": "SMITH",
      "phoneNumber": "6360000000",
      "faxNumber": "6360000001",
      "emailAddress": "JACK_SMITH@XYZ.COM"
    }
  ]
}
```

### 9. Countries {#9-countries}

|      API Call      |                                               Description                                               |       URI        |   Response   |
|--------------------|---------------------------------------------------------------------------------------------------------|------------------|--------------|
| Retrieve Countries | Retrieves the list of ISO country codes that can be submitted in a merchant or principal owner address. | `GET /countries` | HTTP: 200 OK |

```text
GET /countries
```

```json
{
  "countries": [
    { "countryCode": "USA", "regionCode": "US", "name": "United States", "isStatesAvailable": true },
    { "countryCode": "CAN", "regionCode": "CA", "name": "Canada", "isStatesAvailable": true },
    { "countryCode": "GBR", "regionCode": "GB", "name": "United Kingdom", "isStatesAvailable": false },
    { "countryCode": "AFG", "regionCode": "AS", "name": "Afghanistan", "isStatesAvailable": false }
  ]
}
```

### 10. States {#10-states}

|    API Call     |                                       Description                                        |                  URI                   |   Response   |
|-----------------|------------------------------------------------------------------------------------------|----------------------------------------|--------------|
| Retrieve States | Retrieves the list of states/provinces for a given country (required for US and Canada). | `GET /countries/{country_code}/states` | HTTP: 200 OK |

```text
GET /countries/USA/states
```

```json
{
  "states": [
    { "stateCode": "AL", "name": "Alabama" },
    { "stateCode": "AK", "name": "Alaska" },
    { "stateCode": "AZ", "name": "Arizona" },
    { "stateCode": "CA", "name": "California" },
    { "stateCode": "NY", "name": "New York" }
  ]
}
```

### 11. Cities {#11-cities}

|    API Call     |                                Description                                 |                  URI                   |   Response   |
|-----------------|----------------------------------------------------------------------------|----------------------------------------|--------------|
| Retrieve Cities | Retrieves the list of cities for a given country (and optionally a state). | `GET /countries/{country_code}/cities` | HTTP: 200 OK |

```text
GET /countries/USA/cities?state_code=NY
```

```json
{
  "cities": [
    "New York",
    "Buffalo",
    "Rochester",
    "Albany",
    "Syracuse"
  ]
}
```

Tip: You can also run every endpoint without writing code using our [Postman Collection](https://developer.mastercard.com/match/documentation/developer-tools/postman-collection/index.md).

## Negative testing {#negative-testing}

Negative testing confirms that your client handles failures gracefully. Expand each case below to view an invalid request and the expected error result.
`POST /merchants/add-merchants`

```json
{
  "addMerchantRequest": {
    "merchant": {
      "name": "THE BAIT SHOP",
      "merchantId": "ABED-1234"
    }
  }
}
```

Expected result: `400 Bad Request` because `acquirerId` is required.
`POST /termination-inquiries`

```json
{
  "terminationInquiryRequest": {
    "acquirerId": "1996",
    "merchant": {
      "doingBusinessAsName": "BAIT R US"
    }
  }
}
```

Expected result: `400 Bad Request` because the merchant `name` is required.
`GET /merchants/new-merchant-insights/INVALID-IRN-0000`

Expected result: `404 Not Found` because no records exist for the provided `inquiry_ref_num`.
`GET /retros/retro-inquiry-details/INVALID-IRN-0000`

Expected result: `404 Not Found` because no retroactive match exists for the provided `inquiry_ref_num`.
`POST /contact-details`

```json
{
  "contactRequest": {}
}
```

Expected result: `400 Bad Request` because `acquirerId` is required.
`POST /merchants/performance-indicators`

```json
{
  "criteria": [
    { "field": "NATIONALTAXID" }
  ]
}
```

Expected result: `400 Bad Request` because the criteria `value` is required.
`POST /termination-inquiries` with a missing or malformed Authorization (OAuth) header.

Expected result: `401 Unauthorized` because OAuth signature verification failed.

For the complete list of response codes, reason codes, and formatting rules, see [Code and Formats](https://developer.mastercard.com/match/documentation/code-and-formats/index.md).

## MTF Testing {#mtf-testing}

### New Merchant Insights Test Case Scenarios {#new-merchant-insights-test-case-scenarios}

The MATCH Pro Mastercard Test Facility (MTF) environment includes predefined New Merchant Insights test scenarios that help customers test their integration, validate response handling, and understand how New Merchant Insights scores and signals are returned in a controlled test environment.

Use the 9 scenarios below to validate your New Merchant Insights integration. For each scenario, submit the exact test case index value listed. When creating a new inquiry, enter the merchant name and test case index together in the Merchant Name field. For example, enter Sweets Shoppe TC000 to return the predefined response for TC000. In addition to the Merchant Name field, all required fields must be provided for each test case before submission. The returned results are based on the selected test case index rather than the values entered in the request. Any applicable production warnings may also be included in the response.

When the request matches a predefined scenario, New Merchant Insights will return the corresponding response shown. If a Test Case Index is not provided, the default response for TC000 will be returned.

### Response JSON Examples {#response-json-examples}

#### TC000 (Example: Sweets Shoppe TC000 ) {#tc000-example-sweets-shoppe-tc000-}

A low-risk merchant where the entity has been seen on the proprietary Mastercard network, but the merchant has not. The digital presence assessment is completed when a URL is provided in the inquiry. This response indicates that an online presence was found.

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "merchantRiskScore": {
    "score": 0.351,
    "reasonCode": "LF, LE, LI",
    "reasonDescription": "LF - Low Inquiry Attribute Consistency Risk, LE - Low Inquiry Attribute Completeness Risk, LI - Low Inquiry Attribute Volatility Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": null,
      "sameMerchantLocationPrincipalLocation": null,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 0,
      "numPerMerchantPrincipalPair": 1,
      "numPerMerchantPhone": null,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": null,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": true,
      "entityFirstSeenDays": 197,
      "entityLastSeenDays": 3,
      "entityMCCCount": 1,
      "entityMerchantCount": 1,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "low",
      "negativeReviewPresence": "low",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 71,
      "hasHijackingProtection": false,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 2,
      "hasMinimalContent": false,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": false
    }
  },
  "assessmentTimestamp": "2026-07-09T12:15:56Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC001 {#tc001}

A high-risk merchant with no prior Mastercard network history. The risk is driven by digital presence signals, including a medium level of negative reviews and a website that does not use strong encryption.

```json
{
  "merchantProfileRefId": "MPRID-54536334-013NDV4QAVZKTS5FBWE69GRRFS",
  "merchantRiskScore": {
    "score": 0.701,
    "reasonCode": "HJ, HK, HM",
    "reasonDescription": "HJ - High Reputational Risk, HK - High Website Security Risk, HM - High Business Data Risk",
    "riskClass": "HIGH"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": 0.75,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 0,
      "numPerMerchantPrincipalPair": 0,
      "numPerMerchantPhone": 0,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": 0,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": false,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": false,
      "socialMediaEngagement": null,
      "negativeReviewPresence": "medium",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 137,
      "hasHijackingProtection": false,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 2,
      "hasMinimalContent": false,
      "hasStrongEncryption": false,
      "redirectsToExternalSite": true,
      "refundsProhibited": true
    }
  },
  "assessmentTimestamp": "2026-12-21T15:05:07Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC002 {#tc002}

A high-risk merchant where the entity has previously appeared on the Mastercard network, but the merchant was not found. Inquiry Insights contain high-velocity and high-volatility patterns, along with several risky digital presence signals.

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "merchantRiskScore": {
    "score": 0.705,
    "reasonCode": "HH, HI, HE",
    "reasonDescription": "HH - High Inquiry Attribute Velocity Risk, HI - High Inquiry Attribute Volatility Risk, HE - High Inquiry Attribute Completeness Risk",
    "riskClass": "HIGH"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": 0.75,
      "uniqueAcquirersPerMerchantAddress": 1,
      "numPerPrincipal": 6,
      "numPerMerchantPrincipalPair": 11,
      "numPerMerchantPhone": 10,
      "numPerMerchantAddress": 1,
      "uniqueMerchantPhonePerMerchantAddress": 2,
      "uniqueMerchantAddressPerMerchantPhone": 1,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 1
    },
    "networkInsights": {
      "hasEntityMatch": true,
      "entityFirstSeenDays": 97,
      "entityLastSeenDays": 43,
      "entityMCCCount": 4,
      "entityMerchantCount": 6,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "medium",
      "negativeReviewPresence": "high",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 360,
      "hasHijackingProtection": true,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 1,
      "hasMinimalContent": false,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": true
    }
  },
  "assessmentTimestamp": "2026-02-23T21:04:34Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC003 {#tc003}

A low-risk merchant with both an entity match and a direct merchant match found in Mastercard's proprietary network. The response includes merchant signals, such as chargeback and authorization rates, and a digital presence assessment when a URL is provided in the inquiry.

```json
{
  "merchantProfileRefId": "MPRID-53637-02KTSV4R01ARNDETSV4RRFF9GE",
  "merchantRiskScore": {
    "score": 0.375,
    "reasonCode": "LE, LI, LH",
    "reasonDescription": "LE - Low Inquiry Attribute Completeness Risk, LI - Low Inquiry Attribute Volatility Risk, LH - Low Inquiry Attribute Velocity Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": null,
      "sameMerchantLocationPrincipalLocation": null,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 0,
      "numPerMerchantPrincipalPair": 0,
      "numPerMerchantPhone": null,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": null,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": true,
      "entityFirstSeenDays": 234,
      "entityLastSeenDays": 1,
      "entityMCCCount": 1,
      "entityMerchantCount": 1,
      "hasMerchantMatch": true,
      "merchantChargebackRate": 0.00002,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": 0.99998,
      "merchantFirstSeenDays": 200,
      "merchantLastSeenDays": 1,
      "merchantNumPastAcquirers": 1
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "low",
      "negativeReviewPresence": "medium",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 5414,
      "hasHijackingProtection": true,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 1,
      "hasMinimalContent": true,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": false
    }
  },
  "assessmentTimestamp": "2026-04-18T04:07:47Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC004 {#tc004}

A medium-risk merchant with no prior Mastercard network history. Mixed digital presence signals elevate the merchant's risk above low risk.

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "merchantRiskScore": {
    "score": 0.65,
    "reasonCode": "MJ, MP, MK",
    "reasonDescription": "MJ - Medium Reputational Risk, MP - Medium Domain Risk, MK - Medium Website Security Risk",
    "riskClass": "MEDIUM"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": 1,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": null,
      "numPerMerchantPrincipalPair": null,
      "numPerMerchantPhone": 0,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": 0,
      "uniqueMerchantAddressPerMerchantPhone": null,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": false,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "low",
      "negativeReviewPresence": "high",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 579,
      "hasHijackingProtection": true,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": false,
      "hasReplicatedContent": false,
      "numIPs": 1,
      "hasMinimalContent": false,
      "hasStrongEncryption": false,
      "redirectsToExternalSite": true,
      "refundsProhibited": false
    }
  },
  "assessmentTimestamp": "2026-01-05T16:44:10Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC005 {#tc005}

A low-risk merchant that is new to the Mastercard network, with neither an entity match nor a merchant match found. Although some digital presence signals may be mixed, the overall assessment indicates a low risk.

```json
{
  "merchantProfileRefId": "MPRID-53637-02KTSV4R01ARNDETSV4RRFF9GE",
  "merchantRiskScore": {
    "score": 0.271,
    "reasonCode": "LF, LE, LH",
    "reasonDescription": "LF - Low Inquiry Attribute Consistency Risk, LE - Low Inquiry Attribute Completeness Risk, LH - Low Inquiry Attribute Velocity Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": null,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": null,
      "numPerMerchantPrincipalPair": null,
      "numPerMerchantPhone": 0,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": 0,
      "uniqueMerchantAddressPerMerchantPhone": null,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": false,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "medium",
      "negativeReviewPresence": "low",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 181,
      "hasHijackingProtection": false,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": true,
      "hasReplicatedContent": false,
      "numIPs": 1,
      "hasMinimalContent": true,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": false
    }
  },
  "assessmentTimestamp": "2026-11-01T15:54:19Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": []
}
```

#### TC006 {#tc006}

A low-risk merchant where certain information could not be generated. The response includes warning messages indicating that a Merchant Profile Reference ID could not be assigned and that a digital presence assessment is unavailable.

```json
{
  "merchantProfileRefId": null,
  "merchantRiskScore": {
    "score": 0.324,
    "reasonCode": "LE, LI, LF",
    "reasonDescription": "LE - Low Inquiry Attribute Completeness Risk, LI - Low Inquiry Attribute Volatility Risk, LF - Low Inquiry Attribute Consistency Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": 0.75,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 0,
      "numPerMerchantPrincipalPair": 24,
      "numPerMerchantPhone": 0,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": 0,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": false,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": null,
      "socialMediaEngagement": null,
      "negativeReviewPresence": null,
      "hasFootTraffic": null
    },
    "domainInsights": {
      "numAssociatedRedirects": null,
      "daysSinceRegistration": null,
      "hasHijackingProtection": null,
      "isResolvable": null
    },
    "websiteInsights": {
      "hasMaliciousActivity": null,
      "hasReplicatedContent": null,
      "numIPs": null,
      "hasMinimalContent": null,
      "hasStrongEncryption": null,
      "redirectsToExternalSite": null,
      "refundsProhibited": null
    }
  },
  "assessmentTimestamp": "2026-04-23T17:56:40Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": [
    {
      "code": "PARTIAL_DIGITAL_PRESENCE_ASSESSMENT",
      "detail": "Unable to generate complete digitalPresenceAssessment results, partial results returned."
    },
    {
      "code": "FAILED_MPRID_GENERATION",
      "detail": "Merchant Profile RefId could not be assigned."
    }
  ]
}
```

#### TC007 {#tc007}

A high-risk merchant where a digital presence assessment is unavailable because no URL was provided in the inquiry. The response includes a warning indicating that no digital presence assessment is available. The risk is driven primarily by network assessment signals.

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "merchantRiskScore": {
    "score": 0.726,
    "reasonCode": "HI, HF, HH",
    "reasonDescription": "HI - High Inquiry Attribute Volatility Risk, HF - High Inquiry Attribute Consistency Risk, HH - High Inquiry Attribute Velocity Risk",
    "riskClass": "HIGH"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": true,
      "sameMerchantLocationPrincipalLocation": 0,
      "uniqueAcquirersPerMerchantAddress": 0,
      "numPerPrincipal": 3,
      "numPerMerchantPrincipalPair": 5,
      "numPerMerchantPhone": 4,
      "numPerMerchantAddress": 0,
      "uniqueMerchantPhonePerMerchantAddress": 2,
      "uniqueMerchantAddressPerMerchantPhone": 0,
      "uniqueMerchantPhonePerMerchantPrincipalPair": 0
    },
    "networkInsights": {
      "hasEntityMatch": false,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": false,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": null,
      "socialMediaEngagement": null,
      "negativeReviewPresence": null,
      "hasFootTraffic": null
    },
    "domainInsights": {
      "numAssociatedRedirects": null,
      "daysSinceRegistration": null,
      "hasHijackingProtection": null,
      "isResolvable": null
    },
    "websiteInsights": {
      "hasMaliciousActivity": null,
      "hasReplicatedContent": null,
      "numIPs": null,
      "hasMinimalContent": null,
      "hasStrongEncryption": null,
      "redirectsToExternalSite": null,
      "refundsProhibited": null
    }
  },
  "assessmentTimestamp": "2026-09-17T14:01:54Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": [
    {
      "code": "PARTIAL_DIGITAL_PRESENCE_ASSESSMENT",
      "detail": "Unable to generate complete digitalPresenceAssessment results, partial results returned."
    }
  ]
}
```

#### TC008 {#tc008}

A low-risk merchant where a network assessment is unavailable. The assessment is based primarily on digital presence signals. The response includes warnings indicating the absence of network assessment signals.

```json
{
  "merchantProfileRefId": "MPRID-4564742-01ARZ3NDEKTSV4RRFFQ69G5FBW",
  "merchantRiskScore": {
    "score": 0.49,
    "reasonCode": "LP",
    "reasonDescription": "LP - Low Domain Risk",
    "riskClass": "LOW"
  },
  "networkAssessment": {
    "inquiryInsights": {
      "isValidMerchantPhone": null,
      "sameMerchantLocationPrincipalLocation": null,
      "uniqueAcquirersPerMerchantAddress": null,
      "numPerPrincipal": null,
      "numPerMerchantPrincipalPair": null,
      "numPerMerchantPhone": null,
      "numPerMerchantAddress": null,
      "uniqueMerchantPhonePerMerchantAddress": null,
      "uniqueMerchantAddressPerMerchantPhone": null,
      "uniqueMerchantPhonePerMerchantPrincipalPair": null
    },
    "networkInsights": {
      "hasEntityMatch": null,
      "entityFirstSeenDays": null,
      "entityLastSeenDays": null,
      "entityMCCCount": null,
      "entityMerchantCount": null,
      "hasMerchantMatch": null,
      "merchantChargebackRate": null,
      "merchantRefundRate": null,
      "merchantAuthorizationRate": null,
      "merchantFirstSeenDays": null,
      "merchantLastSeenDays": null,
      "merchantNumPastAcquirers": null
    }
  },
  "digitalPresenceAssessment": {
    "businessInsights": {
      "hasSocialMedia": true,
      "socialMediaEngagement": "high",
      "negativeReviewPresence": "low",
      "hasFootTraffic": false
    },
    "domainInsights": {
      "numAssociatedRedirects": 0,
      "daysSinceRegistration": 99,
      "hasHijackingProtection": false,
      "isResolvable": true
    },
    "websiteInsights": {
      "hasMaliciousActivity": true,
      "hasReplicatedContent": false,
      "numIPs": 2,
      "hasMinimalContent": false,
      "hasStrongEncryption": true,
      "redirectsToExternalSite": false,
      "refundsProhibited": false
    }
  },
  "assessmentTimestamp": "2026-08-27T23:10:19Z",
  "assessmentStatus": "COMPLETED",
  "insightId": "value-programitically-set",
  "inquiryRefNumber": "value-programitically-set",
  "warnings": [
    {
      "code": "PARTIAL_INQUIRY_INSIGHTS",
      "detail": "Unable to generate complete inquiryInsight results, partial results returned."
    },
    {
      "code": "PARTIAL_NETWORK_INSIGHTS",
      "detail": "Unable to generate networkInsights features."
    }
  ]
}
```

## Next Steps {#next-steps}

Continue with the next section:

* [Code and Formats](https://developer.mastercard.com/match/documentation/code-and-formats/index.md) for error codes, descriptions, and resolution guidance.