Initiate Merchant Query

Submit information about a merchant to begin the process of querying the merchant history in the databases of the card networks.

This method validates the data in your request.

This is the first step in the process of querying the card networks about a potential new merchant. When this step is completed successfully, proceed to Retrieve Query Results.

Parameters

Request Header Parameters

Request Body Parameters

- partner_merchant_reference
- ID of the merchant, defined by the partner.
- Length: 0-60
- Regex: string/^[\w\s\!\@\#\$\%\^\&\*\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/
- partner_query_reference
- Unique ID of the query request, defined by the partner.
- Length: 0-60
- Regex: string/^[\w\s\!\@\#\$\%\^\&\*\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/
- queried_merchant
- Information about the merchant who is the subject of the query.
  address
  Details of the merchant's business address.
  address_line_1
  Line 1 of the address, such as a building number and street name.
  String with letters, numbers, numeric letters, and spaces. Applicable street details in this order: building number/name, street number and name, shop number, floor number.
  Length: 1-60
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,60}
  address_line_2
  Line 2 of the address, such as a suite or apartment number, or the name of a named building.
  String with letters, numbers, numeric letters, and spaces.
  Length: 1-60
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,60}
  city
  City portion of the address.
  String with letters, numbers, and spaces.
  Length: 1-20
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,20}
  country
  Code for the country.
  The two-letter ISO 3166-1 ALPHA-2 country code.
  Length: 2
  Regex: string([A-Z]){2}
  postal_code
  Postal code portion of the address.
  String with letters, numbers, and spaces.
  Length: 1-10
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,10}
  business_category
  The category of the merchant's business. One of the following:
  Merchant
  Payment Facilitator
  Independent Sales Organization
  Marketplace
  Staged Digital Wallet Operator
  Sponsored Merchant
  dba_name
  The "doing business as" name of the merchant.
  String that starts and ends with any combination of characters, whitespace, a specified range of Latin letters with diacritics, and a specific set of special characters.
  Length: 4-60
  Regex: string^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\'\.\/\;\:\&\$\#\!\+\?\@\=\\]{4,60})$
  email
  The primary email address of the merchant.
  String that starts with a combination of letters, numbers, ., _, %, or - before an @ sign. After the @ sign, a domain name with letters, numbers, ., or -, ending with a dot and a 2 to 4 letter domain type, such as .com. For example: billsmith@snapphoto.com
  Length: Maximum - 90
  Regex: string[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\.[a-zA-Z]{2,4}
  is_ecommerce
  Indicates whether the merchant trades through the internet.
  legal_name
  The registered legal name of the merchant.
  String that starts and ends with any combination of characters, whitespace, a specified range of Latin letters with diacritics, and a specific set of special characters.
  Length: 4-60
  Regex: string^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\'\.\/\;\:\&\$\#\!\+\?\@\=\\]{4,60})$
  mcc
  Merchant category codes of the merchant's business.
  Array of strings. Numbers or US letters. Maximum - 5 items. For example: ["5411", "5812"]
  Length of each string: 4
  Regex: strings[0...5]
  phone_numbers
  Business phone numbers of the merchant.
  Array of strings. E.164 format, starting with +. Maximum - 2.
  Length of each phone number: 7-18
  Regex: string^((\+\d{1,3}($\d{1,3}$|(\d{1,3}))\d{1,5})|(($\d{2,6}$)|(\d{2,6})))(\d{3,4})(\d{3,4})
  principals
  Details of the registered principal owners of the merchant. Maximum - 3.
  address
  Details of the owner's business address.
  address_line_1
  Line 1 of the address, such as a building number and street name.
  String with letters, numbers, numeric letters, and spaces. Applicable street details in this order: building number/name, street number and name, shop number, floor number.
  Length: 1-60
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,60}
  address_line_2
  Line 2 of the address, such as a suite or apartment number, or the name of a named building.
  String with letters, numbers, numeric letters, and spaces.
  Length: 1-60
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,60}
  city
  City portion of the address.
  String with letters, numbers, and spaces.
  Length: 1-20
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,20}
  country
  Code for the country.
  The two-letter ISO 3166-1 ALPHA-2 country code.
  Length: 2
  Regex: string([A-Z]){2}
  postal_code
  Postal code portion of the address.
  String with letters, numbers, and spaces.
  Length: 1-10
  Regex: string[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,10}
  email
  The primary email address of the owner.
  String that starts with a combination of letters, numbers, ., _, %, or - before an @ sign. After the @ sign, a domain name with letters, numbers, ., or -, ending with a dot and a 2 to 4 letter domain type, such as .com. For example: davidsmith@snapphoto.com
  Length: Maximum - 90
  Regex: string[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\.[a-zA-Z]{2,4}$
  first_name
  The first name of the owner.
  String that starts and ends with any combination of characters, whitespace, a specified range of Latin letters with diacritics, and a specific set of special characters.
  Length: 1-35
  Regex: string^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\'\`\.\/\?\\]{1,35})$
  last_name
  The family name of the owner.
  String that starts and ends with any combination of characters, whitespace, a specified range of Latin letters with diacritics, and a specific set of special characters.
  Length: 1-40
  Regex: string^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\'\`\.\/\?\\]{1,40})$
  middle_initial
  The initial letter of the owner's middle name.
  String that starts and ends with any combination of characters, whitespace, a specified range of Latin letters with diacritics, and a specific set of special characters.
  Length: Maximum - 1
  Regex: string^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\'\`\.\/\?\\]{1})$
  phone_number
  The phone number of the owner.
  Country and area codes, followed by the main part of the phone number. For example: +861071111222
  Length: Maximum - 18
  Regex: string^((\+\d{1,3}($\d{1,3}$|(\d{1,3}))\d{1,5})|(($\d{2,6}$)|(\d{2,6})))(\d{3,4})(\d{3,4})
  url
  Web addresses associated with the merchant.
  Array of strings. Numbers or US letters. Maximum - 3 items. For example: ["https://fourstarmarket.com", "https://fourstarmarket.net"]
  Length: Maximum - 40
  Regex: strings[0...3]
- search_criteria
- Specifies search criteria for the query.
  search_area
  The geographic range of the query. One of the following:
  global - The query is geographically unlimited.
  local - The query is limited to the merchant's country.
  regional - The query is limited to the merchant's region, such as APAC.

Response Parameters

- operation_id
- ID of the query request operation. UUID.
- partner_merchant_reference
- ID of the merchant, defined by the partner.
- partner_query_reference
- Unique ID of the query request, defined by the partner.
- status
- Status of the Card Network Lookup Service query. One of the following:
  ERROR - The query failed.
  IN_PROGRESS - The query is being processed. Results are not available.
  PARTIAL - The query process is partially complete. Some results are available.
  PROCESSED - The query process is complete. All results are available.

/v1/cnl/termination_query

Initiate Merchant Query - Valid Request

curl -X post
https://sandboxapi.rapyd.net/v1/cnl/termination_query
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '{
    "partner_merchant_reference": "ABCDEFGH",
    "partner_query_reference": "12345678",
    "search_criteria": {
        "search_area": "global"
    },

    "queried_merchant": {
        "legal_name": "Four Star Market, Ltd.",
        "dba_name": "Four Star Market",
        "address": {
            "address_line_1": "123 Main Street",
            "address_line_2": "",
            "city": "London",
            "country": "GB",
            "postal_code": "12345"
        },
        "phone_numbers": [
            "+445555555555"
        ],
        "business_category": "Merchant",
        "principals": [{
                "first_name": "John",
                "middle_initial": "A",
                "last_name": "Doe",
                "email": "john.doe@fourstarmarket.net",
                "address": {
                    "address_line_1": "123 First Street",
                    "address_line_2": "",
                    "postal_code": "12345",
                    "city": "London",
                    "country": "GB"
                },
                "phone_number": "+449999999999"
            }
        ],
        "is_ecommerce": false,
        "email": "service@fourstarmarket.com",
        "url": [
            "https://fourstarmarket.com"
        ]
    }
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "4998cec5-72ac-46d7-b3bd-65bd631a4e78"
    },
    "data": {
        "status": "IN_PROGRESS",
        "operation_id": "4998cec5-72ac-46d7-b3bd-65bd631a4e78",
        "partner_query_reference": "12345678",
        "partner_merchant_reference": "ABCDEFGH"
    }
}

Initiate Merchant Query - Invalid Request: Empty search_criteria

curl -X post
https://sandboxapi.rapyd.net/v1/cnl/termination_query
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '{
    "partner_merchant_reference": "ABCDEFGH",
    "partner_query_reference": "12345678",
    "search_criteria": {},
    "queried_merchant": {
        "legal_name": "Four Star Market, Ltd.",
        "dba_name": "Four Star Market",
        "address": {
            "address_line_1": "123 Main Street",
            "address_line_2": "",
            "city": "London",
            "country": "GB",
            "postal_code": "12345"
        },
        "phone_numbers": [
            "+445555555555"
        ],
        "business_category": "Merchant",
        "principals": [{
                "first_name": "John",
                "middle_initial": "A",
                "last_name": "Doe",
                "email": "john.doe@fourstarmarket.net",
                "address": {
                    "address_line_1": "123 First Street",
                    "address_line_2": "",
                    "postal_code": "12345",
                    "city": "London",
                    "country": "GB"
                },
                "phone_number": "+449999999999"
            }
        ],
        "is_ecommerce": false,
        "email": "service@fourstarmarket.com",
        "url": [
            "https://fourstarmarket.com"
        ]
    }
}
'

{
    "status": {
        "error_code": "INVALID_FIELDS",
        "status": "ERROR",
        "message": "The request attempted an operation, but one of the fields contained a value that is not valid. The request was rejected. Corrective action: The name of the field appears at the end of the response code. Use a valid value.",
        "response_code": "INVALID_FIELDS - [SEARCH_CRITERIA]",
        "operation_id": "28d623d8-89dd-43b7-aac4-4d07aea25072"
    }
}

In this section:

Documentation

Initiate Merchant Query

Parameters

Request Header Parameters

Request Body Parameters

Response Parameters

Search results