Skip to main content

Documentation

Card Network Lookup Service

Investigate a potential new merchant for experience with acquirers.

The Card Network Lookup Service (CNLS) provides information about the prior credit card experience of a potential new merchant. The service is part of industry efforts to reduce risk and fraud. Visa and Mastercard maintain records of merchants whose contracts were terminated by their acquirers. If the termination reason meets specified criteria, the merchant and reason are registered. Use this information to determine whether you want to proceed with onboarding.

The card networks do not provide guidelines for interpreting the results of this query.

This service is relevant to a payment facilitator partner.

CNLS Prerequisites

  • Define an ID for the merchant.

  • Define an ID for the query request.

For details, see Initiate Merchant Query: partner_merchant_reference and partner_query_reference.

Searching for a Merchant's Termination History

To find whether a merchant appears in a card network database of terminated merchants:

  1. Initiate a merchant query.

    1. Define the prerequisites. See CNLS Prerequisites.

    2. Run Initiate Merchant Query.

    3. In the response, verify that data.status is IN_PROGRESS.

    4. Proceed to the next step.

  2. Retrieve the query results.

    Completing the query process may take time. Rapyd recommends implementing a polling mechanism for retrieving the results.

    1. Implement a polling mechanism that repeatedly does the following:

      1. Run Retrieve Query Results.

      2. Compare the responses for changed information.

      3. Notify when the value of data.query_info.query_status changes.

    2. Analyze the query results in the response. See Understanding Query Results.

Understanding Query Results

The Retrieve Query Results response include information about different types of matches for the merchant query.

A query match is when your merchant query matches elements of a previous merchant query in the card network termination database. This means that the merchant that you looked for shares data with a merchant that was previously searched for.

A registered match is when your merchant query matches elements of a merchant termination registration in the card network termination database. This means that an acquirer terminated the contract of a merchant that shares data with the merchant that you looked for.

The data.match_stats object tells you how many matches of each type were found. In this example, the results include one registered match and one query match.

	"match_stats": {
            "registered_match_count": 1,
            "query_match_count": 1
        },

The data.matches object provides details of each match, including the type.

The first parts tells you the card network termination database, the type of match, and the data points that match your query, either exactly or partially.

In this example, the VISA network found a registered match where your query exactly matches three fields and partially matches one field.

	"matches": [
            {
                "card_network": "VISA",
                "match_type": "registered match",
                "exact_match": [
                    "merchant.address.city",
                    "merchant.address.postal_code",
                    "merchant.address.country"
                ],
                "partial_match": [
                    "merchant.address.address_line_1"
                ],

In this example, the MASTERCARD network found a query match where your query exactly matches one field.

	{
                "card_network": "MASTERCARD",
                "match_type": "query match",
                "exact_match": [
                    "merchant.address"
                ],
                "partial_match": [],

The data.matches.matched_merchant and data.matches.registration_info objects provide more details.

If you are interested in only one match type, ignore the count and match details of the other type.

CNLS Error Messages

In this section: