Board a Merchant

One of the key benefits to partnering with us is maintaining the end-to-end merchant experience for your customers, starting with merchant boarding. This guide focuses on the API requests, key data, and validation needed to submit an application that will successfully onboard a new merchant.

Before starting the steps in this guide, make sure you:

• Get set up in our Sandbox test environment:
  • Get registered
  • Get Partner-level Sandbox test credentials (contact our support team)
  • Create an access token

To improve the chances of real-time “know your customer” (KYC) validation, you can perform an Address Lookup, which ensures that the address is formatted correctly in your merchant’s application. It searches for all addresses with a specified house number within a postal code. The applicant can then be presented with possible addresses and select the one that best matches their address.

When you create a merchant account, you can include the provided reference number for the address to facilitate the KYC validation process. This is recommended for all addresses when creating a merchant in the United Kingdom. Not performing this step may result in increased KYC failures.

Sample request

Sample response

{  
    "Addresses": \[  
        {  
            "reference": "28030106476",  
            "line\_1": "2649 BAKER STREET",  
            "line\_2": "Primrose Cottage",  
            "line\_3": "Harrow",  
            "city": "Beverly Hills",  
            "state": "CAMBS",  
            "country": "GB",  
            "postal\_code": "HA1 1HS"  
        }  
    \],  
    "action": \[  
        {  
            "id": "ACT\_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",  
            "type": "ADDRESS\_LOOKUP",  
            "time\_created": "2021-05-03T21:23:39.718Z",  
            "result\_code": "SUCCESS",  
            "app\_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",  
            "app\_name": "demo\_app"  
        }  
    \]  
}

The key components of the data collected for your merchant’s application include the following:

• Addresses – Business addresses associated with the account. This data may be used in due-diligence processes.
• Pricing Profile – As a partner, you can request merchant-pricing configuration for the merchants you board. Create as many pricing profiles as your business needs as long as you do it prior to merchant boarding. Then just pass the pricing-profile name in your request.
• Payment Processing Statistics – Projections for processing volumes that will be processed through this merchant.
• Payment Methods – Bank accounts or cards associated with the merchant to receive deposits or pay fees.
• Persons – Individuals associated with the account. This should include all beneficial owners who hold 25% or more stake in the business. Due diligence and KYC validations are performed using the information provided here. Your merchant applications should include valid, legal personal data (including legal names, IDs, addresses, and so forth).
• Products – Refers to the capabilities that you are enabling for this merchant. Depending on requested products, a merchant may have multiple accounts.

Sample request

For complete details on API requests and responses, see [POST] Board Merchant in the API Explorer.

For region-specific examples of boarding requests, see Merchants in the API Explorer.

Sample response

Creating a merchant is an asynchronous process. Once you complete the initial request, the response will contain the relevant Merchant ID (MER_ID), which you can store. You then need to stand by for one or more webhook notifications to retrieve the Account ID(s).

For more information, see the Merchant account hierarchy section of our boarding overview.

{
    "id": "MER_fefa25b0f0144c67a2c7b69c392c6c3c",
    "name": "John Doe Merchant ",
    "status": "UNDER_REVIEW",
    "type": "MERCHANT",
    "time_created": "2022-11-09T23:44:57Z",
    "time_last_updated": "2022-11-09T23:44:57Z",
    "status_description": "Merchant Boarding in progress",
    "action": {
        "id": "ACT_sq8xweMitE2a42KDuPGmYpoJQDdr2l",
        "type": "MERCHANT_CREATE",
        "time_created": "2022-11-09T23:44:57.428Z",
        "result_code": "SUCCESS",
        "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
        "app_name": "demo_app"
    }
}

Once you submit the application and get the MER_ID in the response, our system performs a KYC validation in parallel.

• If the KYC validation is successful, the merchant is boarded and enabled. You will receive a webhook notification with a merchant status of ACTIVE as well as one for all ACCOUNTS created for this merchant (for more information, see the Merchant account hierarchy section of our boarding overview). ACTIVE merchants can start accepting transactions immediately.
• If a merchant fails KYC validation, the WITH_MERCHANT status will indicate this. See our guide for instructions on uploading documentation to request further review and activation.

Sample webhook notification

{
  "id": "MER_4d9ac02fcdf64c57aae513fd1aaf18f0",
  "name": "John Doe Merchant 1 ",
  "status": "ACTIVE",
  "type": "MERCHANT",
  "time_created": "2023-03-15T15:00:49.000Z",
  "time_last_updated": "2023-03-15T15:01:31.000Z",
  "email": "james.mason@example.com",
  "address": {
    "line_1": "1 Business Address",
    "line_2": "Suite 2",
    "line_3": "foyer",
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30346",
    "country": "US"
  },
  "contact_phone": {
    "country_code": "01",
    "subscriber_number": "8008675309"
  },
  "products": [
    {
      "id": "PRO_TRA_CNP-US-CARD_PP",
      "name": "Card Not Present Transaction processing",
      "account": {
        "id": "TRA_f7ad82b526fb4091984a8478261f3bf9",
        "type": "TRANSACTION_PROCESSING",
        "name": "718576205_305901",
        "status": "ACTIVE",
        "channel": "CNP",
        "time_created": "2023-03-15T15:01:28.000Z",
        "permissions": [
          "BAT_GET_Single",
          "ACT_GET_Single_Logs",
          "ACC_GET_List",
          "ACC_GET_Single_Platform",
          "GET_Single",
          "TRN_POST_Authorize",
          "TRN_POST_Split",
          "VER_POST_Verify",
          "ACC_GET_Single",
          "TRN_POST_Adjust",
          "TRN_POST_Refund",
          "TRN_GET_Single",
          "AUT_POST_Results",
          "TRN_POST_Initiate",
          "ACT_POST_Auto_Action",
          "AUT_POST_Initiate",
          "AUT_POST_Check_Availability",
          "BAT_POST_Close",
          "TRN_POST_Confirm",
          "TRN_POST_Reverse",
          "TRN_POST_Capture",
          "ACT_GET_Single",
          "",
          "TRN_GET_List",
          "ACT_GET_List"
        ]
      }
    }
  ],
  "action": {
    "id": "ACT_vja2mabXbWE6F1cnP2jBIafdYlaidE",
    "type": "MERCHANT_CREATE_STATUS_NOTIFICATION",
    "time_created": "2023-03-15T15:01:50.053Z",
    "result_code": "SUCCESS",
    "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
    "app_name": "demo_app"
  }
}

To get a deeper understanding of merchant boarding, we recommend that you use our provided integration references. For the full detailed API specification, see the API Explorer.

Our QR Code Payments solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Below are recommended next steps for your partner integration.