# Use Cases
source: https://developer.mastercard.com/match/documentation/use-cases/index.md

## Add Terminated Merchant Scenario {#add-terminated-merchant-scenario}

An Authorized User terminates a merchant agreement with a merchant in accordance with the standards listed in the Security Rules and Procedures. The Authorized User can use this request to add the MATCH merchant to the MATCH Pro database using the Add Terminated Merchant request. Authorized Users must add the merchant in MATCH using the Member ID/ICA number under which the merchant's activity was conducted. Acquirers must provide two digits numeric [reason code](https://developer.mastercard.com/match/documentation/index.md#overview) indicating why the relationship was terminated.


Diagram seq-AddTerminatedMerchant


API Reference: `POST /merchants/add-merchants`

<br />

## Termination Inquiry with New Merchant Insights Request Scenario {#termination-inquiry-with-new-merchant-insights-request-scenario}

An Authorized User wants to evaluate the fraud risk associated with a prospective merchant. The acquirer collects the following information from the prospective merchant:   

  1) Merchant's business name, address and contact details  

  2) Merchant's principal owner's name, address, contact details  

  3) Merchant website details like URL

The Authorized User submits a Termination Inquiry API request to MATCH Pro to find out if the merchant has been terminated by another Authorized User in the past five years and also to retrieve New Merchant Insights derived from the merchant's digital presence prior MATCH inquires and history on the Mastercard network. MATCH Pro performs three actions:  

  1. Compares the data provided by the Authorized User with MATCH Merchant records in the database and sends a response back  

  2. Scans the internet to review the prospective merchant's online digital presence  

  3. Searches Mastercard network data for evidence of prior inquiries and historical activity on the network related to the merchant  

For the acquirers subscribed for Merchant Pro Performance Indicators value-added-service will be able to view the Merchants Performance metrics related to Gross Domestic Volume, Approval Rate, Fraud, Chargeback and Compliance information.

The MATCH Pro response includes an Inquiry Reference number (IRN) for future reference.
Diagram seq-TerminationInquiry
API Reference: `POST /termination-inquiries`


API Reference: `GET /merchants/new-merchant-insights/{inquiry_ref_num}`

## Termination Inquiry History Request Scenario {#termination-inquiry-history-request-scenario}

The Authorized User wants to view the inquiry results of inquiries made in the past 365 days. In this situation, the Authorized User can use the Termination Inquiry History API to fetch their past inquiry data using the Inquiry Reference Number.   

MATCH Pro persists all termination inquiry results in its database. Match Service uses the Inquiry reference number sent in the Termination Inquiry History API to retrieve the Inquiry results along with Merchant Performance Indicators for subscribed users saved in its Database. There is no limit to the number of times, acquirers can retrieve historical search results using this API.


Diagram seq-TerminationInquiryHistory


API Reference: `GET /termination-inquiries/{inquiry_ref_num}`

<br />

## Match Pro Performance Indicators Request Scenario {#match-pro-performance-indicators-request-scenario}

An Authorized User wants to monitor and evaluate the ongoing performance and risk profile of a merchant operating on the Mastercard network. To initiate the analysis, the user selects the merchant using the National Tax ID and specifies the desired date range.

The user then submits a Merchant Performance Indicator request through MATCH Pro to retrieve aggregated performance metrics and compliance indicators associated with the merchant's activity.

Upon receiving the request, MATCH Pro performs the following actions:
- Retrieves key data points, including global domestic volume, approval rates, chargebacks, and fraud metrics.
- Aggregates these performance metrics along with compliance program participation data (e.g., BRAM, EFM, ECM)

The resulting insights enable the Authorized User to analyze performance trends, assess merchant risk, and support informed, ongoing decision-making.


Diagram seq-merchantsInsights


API Reference: `POST /merchants/performance-indicators`

<br />

## Retroactive Inquiry Request Scenario {#retroactive-inquiry-request-scenario}

Authorized User A performs an inquiry for a merchant "X Inc" and doesn't find a match. MATCH Pro will keep searching for merchant "X Inc" in the database for the next 360 days. Suppose within the next 360 days, another Authorized User B adds a terminated merchant "X Inc", who matches the search parameters used by Authorized User A. MATCH Pro will send an email notification to Authorized User A indicating that there is a possible retroactive inquiry match. Authorized Users submit the retroactive inquiry list request to retrieve a list of retroactive inquiry matches from the past 30 days. This list of retroactive inquiry matches includes an Inquiry Reference Number, which the Authorized User can submit in the Retroactive Details Request to get more details of the possible merchant match.  


Note: Each day, MATCH Pro automatically conducts a retroactive inquiry search on every merchant to which the acquirer has submitted an inquiry. MATCH Pro automatically deletes retroactive inquiry matches after thirty days. Therefore, Authorized Users should view retroactive inquiries every day to be sure that they do not miss a possible match.   

<br />


Diagram seq-RetroactiveInquiry


API Reference: `POST /retros/retro-lists`

<br />

## Retroactive Inquiry Details Request Scenario {#retroactive-inquiry-details-request-scenario}

The Authorized User uses the Retroactive Inquiry API to retrieve a list of Retroactive Inquiry Reference Numbers which matched the acquirer's previous termination inquiries. The Authorized User then uses Retroactive Inquiry Details API to fetch details of the possible retroactive inquiry matches.

Diagram seq-RetroactiveInquiryDetails
API Reference: `GET /retros/retro-inquiry-details/{inquiry_ref_num}`

## Acquirer Contact Request Scenario {#acquirer-contact-request-scenario}

While onboarding a new merchant, an Authorized User A, finds out that a MATCH merchant was added to MATCH Pro by Authorized User B. Authorized User A wants to investigate further before onboarding the MATCH Merchant and uses the Acquirer Contact API to get contact details of Authorized User B.


Diagram seq-AcquirerContacts


API Reference: `POST /contact-details`

<br />

## Countries Request Scenario {#countries-request-scenario}

While adding or performing an inquiry on a MATCH merchant, the 3-letter ISO country code is required. The Authorized User uses the Countries API to retrieve a list of ISO countries codes that can be submitted in the Country field of the MATCH merchant address or Principal Owner(s) address in the Termination Inquiry Request or the Add Terminated Merchant Request.

Diagram seq-Countries
API Reference: `GET /countries`

## States Request Scenario {#states-request-scenario}

While adding or performing an inquiry on a MATCH Merchant, the 2-letter state or province is required for US and Canada merchants. The Authorized User uses the Countries API to retrieve list of ISO countries codes. The Authorized User then uses States API to fetch the list of states details for specific country that can be submitted in the State/Province field of the MATCH merchant address or Principal Owner(s) address in the Termination Inquiry Request or the Add Terminated Merchant Request.

Diagram seq-States
API Reference: `GET /countries/{country_code}/states`

## Cities Request Scenario {#cities-request-scenario}

While adding or performing an inquiry on a MATCH Merchant, the city is required. The Authorized User submits the Cities API request for the relevant country to fetch the list of cities names for the relevant country or for the relevant country and one of its states. If the relevant city is not returned in the City API for the specified country, users must submit "IsOtherCity: Y" and the relevant city in the City field of the MATCH Merchant address or the Principal Owner address in the Termination Inquiry Request or the Add Merchant Request.

Diagram seq-Cities
API Reference: `GET /countries/{country_code}/cities`