--- title: "Initiate Merchant Query" source_url: https://docs.rapyd.net/en/initiate-merchant-query.html lang: en --- # 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](https://docs.rapyd.net/en/retrieve-query-results.md "Retrieve Query Results"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - partner_merchant_reference - ID of the merchant, defined by the partner. - Length: 0-60 - Regex: `^[\w\s\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$` - - partner_query_reference - Unique ID of the query request, defined by the partner. - Length: 0-60 - Regex: `^[\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-100 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,100}$` - - 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-100 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,100}$` - - city - City portion of the address. - String with letters, numbers, and spaces. - Length: 1-30 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,30}$` - - state - Code for the state. Required only when country is USA. Optional/ignored for all other countries. - The standard US state code (e.g. NY, NJ, TX). Do not use full state names (e.g., "New York") or hyphenated ISO codes ("US-NY"). Uppercase. - Length: 2 - Regex: `([A-Z]){2}` - - country - Code for the country. - The two-letter ISO 3166-1 ALPHA-2 country code. Uppercase. - Length: 2 - Regex: `([A-Z]){2}` > **Note:** > > In the sandbox, the following countries are supported: > > - Finland (FI) > - France (FR) > - Germany (DE) > - Iceland (IS) - - postal_code - Postal code portion of the address. - String with letters, numbers, and spaces. - Length: 1-10 - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,10}$` - - business_category - The business category of the screened merchant. One of the following: - **Merchant** - **Payment Facilitator** - **Independent Sales Organization** - **Marketplace** - **Staged Digital Wallet Operator** - **Sponsored Merchant** - Refers to a sub-merchant that is being screened and onboarded by a payment facilitator (PayFac). - - 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-70 characters - Regex: `^([\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: **johndoe@rapyd.net** - Length: 4-100 characters - - is_ecommerce - Indicates whether the merchant trades through the internet. > **Note:** > > Set to `true` if the merchant supports any online transactions (such as pay by link, virtual terminal, or hosted checkout page), even if the majority of the merchant's transactions are in-store transactions. > > If **true**, `url` is required. - - 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-70 characters - Regex: `^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\(\)\'\.\/\;\:\&\$\#\!\+\?\@\=\\]{4,60})$` - - mcc - Merchant category codes of the merchant's business. - Array of 4-digit numeric strings. Maximum - 5 items. For example: **["5411", "5812"]** - Regex: `^\d{4}$` - - phone_numbers - Business phone numbers of the merchant. - Array of strings. Maximum - 2. - Each string is a phone number in the format of +[country code]/[phone number], where the forward slash (/) represents a separator between the country code and the telephone number. The plus sign before the country code is optional. The country code may only contain digits. The slash is required and must follow the country code. The telephone number may include blank spaces and hyphens (-). For example, in **+1/555 555-5555**, the country code is *1* and the telephone number is *5555555555*. The phone number also may be in E.164 format (**+15555555555**). - Length of each phone number: 7-18 - - principals - Details of the registered principal owners of the merchant. Maximum - 5. - - 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-100 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,100}$` - - 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-100 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,100}$` - - city - City portion of the address. - String with letters, numbers, and spaces. - Length: 1-30 characters - Regex: `^[\p{L}\p{Nd}\p{Nl}\p{Z}]{1,30}$` - - state - Code for the state. Required only when country is USA or Canada. Optional/ignored for all other countries. - The standard USA or Canada state code (e.g. NY, NJ, TX). Do not use full state names (e.g., "New York") or hyphenated ISO codes ("US-NY"). Uppercase. - Length: 2 - Regex: `([A-Z]){2}` - - country - Code for the country. - The two-letter ISO 3166-1 ALPHA-2 country code. Uppercase. - Length: 2 - Regex: `([A-Z]){2}` > **Note:** > > In the sandbox, the following countries are supported: > > - Finland (FI) > - France (FR) > - Germany (DE) > - Iceland (IS) - - postal_code - Postal code portion of the address. - String with letters, numbers, and spaces. - Length: 1-10 - Regex: `^[\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: **johndoe@rapyd.net** - Length: Maximum - 90 - Regex: `[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: `` ^([\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: `` ^([\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: `` ^([\w\s\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\�\-\,\(\)\'\`\.\/\?\\]{1})$ `` - - phone_number - The phone number of the owner. - Phone number in the format +[country code]/[phone number], where the forward slash (/) represents a separator between the country code and the telephone number. The plus sign before the country code is optional. The country code may only contain digits. The slash is required and must follow the country code. The telephone number may include blank spaces and hyphens (-). For example, in **+1/555 555-5555**, the country code is *1* and the telephone number is *5555555555*. The phone number also may be in E.164 format (**+15555555555**). - Length: 7-18 - - url - Web addresses associated with the merchant, not including private or internal URLs (10.x.x.x, 172.16.x.x-172.31-x.x, 168.x.x.x) or localhost (127.0.0.1). > **Note:** > > Required if `is_ecommerce` is set to **true**. - Array of alphanumeric strings. Maximum - 3 items. For example: **["https://fourstarmarket.com", "https://fourstarmarket.net"]** - Length: 4-84 characters - Regex: `^(?:(https?|ftp)://)?(?!(10|127)(\.\d{1,3}){3})(?!(169\.254|192\.168)(\.\d{1,3}){2})(?!172\.(1[6-9]|2\d|3[0-1])(\.\d{1,3}){2})((([a-zA-Z0-9\-]+\.)+[a-zA-Z]{2,})|((?!0)(25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d{2}|\d{1,2})){3}))(\:\d{2,5})?(\/[^\s]*)?$` - - search_criteria - Deprecated. ### 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 curl -X post https://sandboxapi.rapyd.net/v1/cnl/termination_query -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' \ -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 Boulevard St Germain", "address_line_2": "", "city": "Paris", "country": "FR", "postal_code": "12345" }, "phone_numbers": [ "+1/555 555-5555" ], "business_category": "Merchant", "principals": [{ "first_name": "John", "middle_initial": "A", "last_name": "Doe", "email": "john.doe@fourstarmarket.net", "address": { "address_line_1": "123 Rue De Rivoli", "address_line_2": "", "postal_code": "12345", "city": "Paris", "country": "FR" }, "phone_number": "+1/555 555-1234" } ], "is_ecommerce": false, "email": "service@fourstarmarket.com", "url": [ "https://fourstarmarket.com" ] } } ' ``` - ```json { "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 - Valid Request for USA address - ```curl curl -X post https://sandboxapi.rapyd.net/v1/cnl/termination_query -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' -H 'signature: your-calculated-signature-here' -H 'timestamp: your-unix-timestamp-here' -d '{ "partner_merchant_reference": "944263678", "partner_query_reference": "944263678", "search_criteria": { "search_area": "global" }, "queried_merchant": { "legal_name": "Sample Trading Ltd", "dba_name": "Sample Trading", "address": { "address_line_1": "123 Main Street", "city": "New York", "country": "US", "state": "NY", "postal_code": "10001" }, "phone_numbers": ["+19175551234"], "business_category": "Merchant", "principals": [ { "first_name": "John", "last_name": "Doe", "email": "john@example.com", "address": { "address_line_1": "1 Principal Rd", "city": "Los Angeles", "country": "US", "state": "CA", "postal_code": "90001" }, "phone_number": "+13105559876" } ], "is_ecommerce": false, "email": "merchant@example.com", "mcc": ["7995"], "url": ["http://example.com"] } } ' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "11b8b789-6425-4bd7-999c-6bf48c35c9bc" }, "data": { "status": "IN_PROGRESS", "operation_id": "11b8b789-6425-4bd7-999c-6bf48c35c9bc", "partner_query_reference": "944263678", "partner_merchant_reference": "944263678" } } ``` - Initiate Merchant Query - Invalid Request: Missing state for USA address - ```curl curl -X post https://sandboxapi.rapyd.net/v1/cnl/termination_query -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' -H 'signature: your-calculated-signature-here' -H 'timestamp: your-unix-timestamp-here' -d '{ "partner_merchant_reference": "944263678", "partner_query_reference": "944263678", "search_criteria": { "search_area": "global" }, "queried_merchant": { "legal_name": "Sample Trading Ltd", "dba_name": "Sample Trading", "address": { "address_line_1": "123 Main Street", "city": "New York", "country": "US", "postal_code": "10001" }, "phone_numbers": ["+19175551234"], "business_category": "Merchant", "principals": [ { "first_name": "John", "last_name": "Doe", "email": "john@example.com", "address": { "address_line_1": "1 Principal Rd", "city": "Los Angeles", "country": "US", "postal_code": "90001" }, "phone_number": "+13105559876" } ], "is_ecommerce": false, "email": "merchant@example.com", "mcc": ["7995"], "url": ["http://example.com"] } } ' ``` - ```json { "status": { "error_code": "INVALID_FIELDS", "status": "ERROR", "message": "INVALID_FIELDS - state is required for USA addresses ...", "response_code": "INVALID_FIELDS" } } ``` - Initiate Merchant Query - Invalid Request: search_criteria - Wrong Value - ```curl curl -X post https://sandboxapi.rapyd.net/v1/cnl/termination_query -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' -H 'signature: your-calculated-signature-here' -H 'timestamp: your-unix-timestamp-here' -d '{ "partner_merchant_reference": "HAPEKDJFMV", "partner_query_reference": "817263", "search_criteria": { "search_area": "france" }, "queried_merchant": { "legal_name": "Four Star Market, Ltd.", "dba_name": "Four Star Market", "address": { "address_line_1": "123 Boulevard St Germain", "address_line_2": "", "city": "Paris", "country": "FR", "postal_code": "12345" }, "phone_numbers": [ "+1/555 555-5555" ], "business_category": "Merchant", "principals": [{ "first_name": "John", "middle_initial": "A", "last_name": "Doe", "email": "john.doe@fourstarmarket.net", "address": { "address_line_1": "123 Rue De Rivoli", "address_line_2": "", "postal_code": "12345", "city": "Paris", "country": "FR" }, "phone_number": "+1/555 555-1234" } ], "is_ecommerce": false, "email": "service@fourstarmarket.com", "url": [ "https://fourstarmarket.com" ] } } ' ``` - ```json { "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" } } ```