Guides

Onboard Merchants using our APIs & Onboarding SDK

Onboarding new merchants is a very simple process. This can be done either through the UI using our hosted/whitelabel onboarding flows, or through our Onboarding APIs and SDKs.

This guide focuses on teaching you how to submit a merchant application using our APIs and SDKs. Use this onboarding option when you want to have full control and flexibility over the onboarding experience where your merchant never has to leave your application. With this onboarding option you will need to use your custom built UIs to collect the required information for the Merchant Application, use our APIs to send us the information, render our Onboarding.js SDK to collect the merchant acceptance, and then submit the application to begin the underwriting and KYC process.

How it Works:

Follow these steps to Onboard a new merchants using our APIs to allow them to begin accepting payments:

  1. Create an Onboarding Template
  2. Collect & send us the merchant information through an API call
  3. Collect the merchant's acceptance to the "Merchant Processing Agreement"
  4. Submit the Merchant Application to begin the Underwriting and KYC process

1. Create an onboarding Template:

To onboard merchants using our APIs you are required to create an onboarding template and add the pricing rates to the template (e.g. Flat Rate 2.90% + $0.30).

📘

For more details on how to create a new Onboarding Template refer to the following guide: Create Onboarding Templates

Once you complete creating the onboarding template collect the "Onboarding Template Id" from the UI (see picture below for reference) which is required to be sent in the payload for the "Create Application API" as the "templateId" property.

IMPORTANT: When creating the "Onboarding Template" pay close attention to the "auto-submit" property. Based on the option selected the application will be either automatically submitted (to begin the underwriting & KYC process) as soon as the merchant principal(s) accept the "Merchant Processing Agreement(s)" or it will be place on hold until you or someone from your team manually submits it. (See Step #4 on this guide for more details on the submission process)


2. Collect & send us the Merchant Information:

Using your application's UI, collect the merchant information that is required to fill out a "Merchant Processing Application".

You will need to send the information form your servers using our Onboarding API. API reference docs can be found in: https://docs.gettrx.com/reference/create-an-application

Below is a sample payload containing a complete Merchant Application for a sample "Demo Business" owned by "John Doe", and that will be processing online payments using the "EdgePay" payment gateway. 

curl --request POST \
     --url https://api-dev.gettrx.com/onboarding/v1/application \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'secretKey: <ENTER_YOUR_SECRET_KEY_HERE>' \
     --data '
{
  "templateId": "<ENTER_YOUR_ONBOARDING_TEMPLATE_ID_HERE>",
  "hasPortalAccess": true,
  "externalReferenceId": "<ENTER_A_CUSTOM_REFERENCE_ID_FROM_YOUR_SYSTEM>",
  "coreBusinessInfo": {
    "legalBusinessName": "John Doe",
    "businessNameDBA": "Demo Business",
    "businessAddress": "Demo Business LLC",
    "businessCity": "Torrance",
    "businessState": "California",
    "businessZipcode": "90502",
    "businessPhone": "(321)-704-1444",
    "customerServicePhone": "(321)-704-1444",
    "billingAddress": "199 Sesame St",
    "billingCity": "Torrance",
    "billingState": "California",
    "billingZipcode": "90502",
    "businessRegistrationType": "llc",
    "businessWebsite": "https://www.gettrx.com",
    "businessRegistrationState": "California",
    "businessStockTicker": null,
    "ein": "11-2345678",
    "businessStartYear": 2024,
    "businessStartMonth": 1,
    "deliveryLeadTime": "immediately",
    "productOrServicesSoldDescription": "Surf Clothes, Apparel, and equipment",
    "currentProcessorName": "Stripe",
    "priorBankruptcyExplanation": null,
    "priorMerchantRelationshipTerminatedExplanation": null
  },
  "processingEstimates": {
    "estimatedMonthlySales": 15000,
    "avgAmountPerSale": 100,
    "highSaleAmount": 500
  },
  "bankingInformation": {
    "bankName": "Bank of America",
    "routingNumber": "121000358",
    "accountNumber": "12345677987"
  },
  "businessPrincipals": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "position": "President",
      "ssn": "771-77-7777",
      "dateOfBirth": "1990-01-01",
      "driverLicenseNumber": "123456788",
      "driverLicenseIssuingState": "California",
      "homeOwnershipType": "own",
      "homeAddress": "1900 Sample St",
      "city": "Malibu",
      "state": "California",
      "zip": "90263",
      "cellNumber": "(321)-704-1444",
      "homePhone": "(321)-704-1444",
      "ownershipPercentage": 100,
      "isControllingPrincipal": true,
      "isPrimaryContact": true,
      "ownerEmail": "[email protected]"
    }
  ],
  "paymentMethods": {
    "onlinePaymentsPercentage": 100,
    "inStorePaymentsPercentage": 0,
    "keyedInPaymentsPercentage": 0
  },
  "processingEquipment": {
    "gateways": [
      {
        "shortId": "edgepay",
        "hasExistingAccount": false
      }
    ],
    "onlinePaymentMethods": [
      {
        "shortId": "other",
        "name": "Sample ISV Name"
      }
    ]
  },
  "motoQuestionnaire": {
    "productAdvertisementChannels": "Google Ads, Facebook Ads",
    "orderPlacementChannel": "Online",
    "productAndServiceDeliveryChannel": "UPS / Fedex",
    "refundPolicyDescription": "30 days full refund",
    "fulfillmentHouseInfo": {
      "fulfillmentHouseServiceName": "FullHouse LLC",
      "fulfillmentHousePhoneNo": "(888)-888-8888"
    }
  },
  "securityInfo": {
    "creditCardDataStoredElectronically": null,
    "isPciCompliant": true
    "priorDataBreachExplanation": null
  }
}
'

You can test the payload with your sandbox account. To do so, just replace the following parameters:

  • secretkey header: Replace the <ENTER_YOUR_SECRET_KEY_HERE> with the secret key for your sandbox environment
  • templateId property: Replace the <ENTER_YOUR_ONBOARDING_TEMPLATE_ID_HERE> with the ID from the onboarding template that you want to use to onboard this merchant . The "Onboarding Template" contains the pricing information for the merchant as well as other configurations and defaults that you may have chosen during Step #1 of this guide.
  • (Optional) externalReferenceId property: Replace the <ENTER_A_CUSTOM_REFERENCE_ID_FROM_YOUR_SYSTEM_HERE> with a custom id generated by your platform. You can also leave as null.

When the application is created successfully, the response will be as follows:

{
    "success": true,
    "code": 201,
    "message": "Application info saved",
    "data": {
        "accountId": "acm_66fdaf73c33bae000157f32a",
        "applicationId": "4a69f17f-c2a1-491a-b1cb-52a321e19e7b",
        "signers": [
            {
                "id": "91d8c647-05cf-4dc2-8885-fef31ce5c879",
                "userId": "0e19b886-2c6e-4485-bdc7-aaaa4ef18c59",
                "type": "primary_signer"
            }
        ]
    }
}

Its key that you store the following information in your servers at a minimum as you will use it later:

  • Account ID (accountId): This is the merchant's internal Account ID. It is required to collect the merchant acceptance. It will also be used later in time to collect payments on behalf of the merchant using your API key.
  • Application ID (applicationId): You can use this ID to retrieve all details related to this application using the GET Application API. API reference docs can be found in: https://docs.gettrx.com/reference/retrieve-application-details. It is also required to collect the merchant acceptance.
  • Signer ID (signers[*].id): This is the ID assigned to each signer in the application. This is also required to collect the merchant acceptance.
  • Signer Type (signers[*].type): This is the type of signer (primary_signer, secondary_signer). For merchants with a single principals, this value will always be "primary_signer". However, for merchants with more than one principal, the principal with the property "isPrimaryContact" set to true will be the "primary_signer". The remaining principals will be tagged "secondary_signer". This property is important as you will always need to collect the merchant acceptance from the primary signer first.

3. Collect the merchant's acceptance to the "Merchant Processing Agreement"

Collecting your merchant's acceptance to the "Merchant Processing Agreement" is a very simple process that consists of 2 steps:

3.1. Retrieve an acceptance token using our APIs

From your server, retrieve an acceptance token for the merchant's principal using our Get Merchant Acceptance Token API. The API reference doc can be found in: https://docs.gettrx.com/reference/retrieve-application-acceptance-token

Below is a sample payload:

curl --request GET \
     --url https://api-dev.gettrx.com/onboard/v1/application/{applicationId}/signers/{signerId}/acceptance-token \
     --header 'accept: application/json' \
     --header 'onBehalfOf: <ENTER_MERCHANT_ACCOUNT_ID_HERE>' \
     --header 'secretKey: <ENTER_YOUR_SECRET_KEY_HERE>'

You can test the payload with your sandbox account. To do so, just replace the following parameters:

  • secretkey header: Replace the <ENTER_YOUR_SECRET_KEY_HERE> with the secret key for your sandbox environment
  • onBehalfOf header: Replace the <ENTER_YOUR_ONBOARDING_TEMPLATE_ID_HERE> with the ID from the onboarding template that you want to use to onboard this merchant. The "Onboarding Template" contains the pricing information for the merchant as well as other configurations. NOTE: You can easily create new "Onboarding Templates" from the portal.
  • applicationId URL Param: Replace this with the application ID stored when creating the merchant application
  • signerId URL Param: Replace this with the signer ID for the stored when creating the merchant application. You should always collect the merchant acceptance from the principal tagged as "primary_signer" first.

Below is a sample successful response containing the acceptance token. 

{
    "success": true,
    "code": 200,
    "message": "Generated acceptance token successfully!",
    "data": {
        "token": "<THE_ACCEPTANCE_TOKEN_WILL_BE_HERE>"
    }
}

IMPORTANT: This token is valid for 5 minutes. You will need to send it to your UI and use it to initialize the merchant acceptance form using our Onboarding JS SDK and collect the merchant's acceptance in that timeframe. You do not need to store this token in your database. You can always request a new one if the case the existing one expires.


3.2. Collect the merchant acceptance from your custom UI using our Onboarding JS SDK

The GETTRX Onboarding JS SDK embeds a agreement acceptance form into your custom page to securely collect principal's acceptance of the Merchant Processing Application and Agreement. Use the code sample below to learn how to collect the acceptance from your custom UI:

👤
Collect Merchant Agreement Acceptance
Open Recipe

📘

TIP:

Run the code sample locally to load the merchant agreement acceptance form. You will need a merchant acceptance token to load the SDK.


IMPORTANT: For multi-principal merchant applications, you will first need to collect the acceptance from primary signer (i.e. principal chosen as primary contact). Once you collect the primary signer acceptance, you can repeat steps 3.1 and 3.2 for each remaining principals in the application.

4. Submit the Merchant Application to begin the Underwriting and KYC process

When creating the onboarding template you must configured the "Auto-submit" option to either "Yes" or "No". The auto-submit property means that as soon as the signature of the principal or principals owning a combined 51% of the legal entity are collected, the application will be auto-submitted to begin the underwriting/KYC process. If your onboarding template is not configured to auto-submit applications, then you will have to either submit it manually through the portal or through our "Submit Application API" (the reference docs can be found at https://docs.gettrx.com/reference/submit-application-to-underwriting).


Additional Considerations

If you are unfamiliar with the information required to submit an application, or you are unsure if you have collected all the information required, you can retrieve the application details and completeness/readiness state through our GET Application Details API. The API reference for this can be found in: https://docs.gettrx.com/reference/retrieve-application-details .

Below is a sample response for an incomplete application:

{
    "success": true,
    "code": 200,
    "message": "Merchant application found",
    "data": {
        "applicationSummary": {
            "id": "f424055d-6ea0-4e8c-8b8f-9f2538ee9de1",
            "status": "created",
            "pricingPlanId": "d749152b-d18b-4a92-bec5-f2690a736c6b",
            "autoSubmitDeal": true,
            "accountId": "acm_66fdb585c33bae000157f32c",
            "externalReferenceId": null,
            "primaryContact": {
                "firstName": "Sydney",
                "lastName": "Grimes",
                "email": "[email protected]",
                "phone": "(321)-704-1444"
            },
            "applicationReadiness": {
                "state": "missing_information",
                "missingInputs": [
                    "coreBusinessInfo.businessAddress",
                    "coreBusinessInfo.businessCity",
                    "coreBusinessInfo.businessState",
                    "coreBusinessInfo.businessZipcode",
                    "coreBusinessInfo.businessPhone",
                    "coreBusinessInfo.customerServicePhone",
                    "coreBusinessInfo.billingAddress",
                    "coreBusinessInfo.billingCity",
                    "coreBusinessInfo.billingState",
                    "coreBusinessInfo.billingZipcode",
                    "coreBusinessInfo.businessRegistrationState",
                    "coreBusinessInfo.businessWebsite",
                    "bankingInformation.bankName",
                    "bankingInformation.routingNumber",
                    "bankingInformation.accountNumber"
                ]
            }
        },
        "coreBusinessInfo": {
            "legalBusinessName": "Ankunding - Gleichner",
            "businessNameDBA": "Ankunding - Gleichner DBA",
            "businessAddress": null,
            "businessCity": null,
            "businessState": null,
            "businessZipcode": null,
            "businessPhone": null,
            "customerServicePhone": null,
            "billingAddress": null,
            "billingCity": null,
            "billingState": null,
            "billingZipcode": null,
            "businessRegistrationType": "llc",
            "businessWebsite": null,
            "businessRegistrationState": null,
            "businessStockTicker": null,
            "maskedEin": "5678",
            "businessStartYear": 2024,
            "businessStartMonth": 1,
            "deliveryLeadTime": "immediately",
            "productOrServicesSoldDescription": "Surf Clothes, Apparel, and equipment",
            "currentProcessorName": "Stripe",
            "priorBankruptcyExplanation": null,
            "priorMerchantRelationshipTerminatedExplanation": null
        },
        "processingEstimates": {
            "estimatedMonthlySales": 15000,
            "avgAmountPerSale": 100,
            "highSaleAmount": 500
        },
        "achProcessingInformation": {
            "achMonthlyVolume": null,
            "achAverageTicket": null,
            "achHighTicket": null,
            "achTransactionTypeDescription": null
        },
        "bankingInformation": {
            "bankName": null,
            "maskedRoutingNumber": null,
            "maskedAccountNumber": null
        },
        "businessPrincipals": [
            {
                "id": "1db46ac1-a109-4f20-ab7f-905374b162b3",
                "firstName": "Sydney",
                "lastName": "Grimes",
                "position": "President",
                "maskedSsn": "7777",
                "dateOfBirth": "1990-01-01",
                "driverLicenseIssuingState": "California",
                "homeOwnershipType": "own",
                "homeAddress": "283 Thaddeus Pines",
                "city": "Malibu",
                "state": "California",
                "zip": "90263",
                "cellNumber": "(321)-704-1444",
                "homePhone": "(321)-704-1444",
                "ownershipPercentage": 100,
                "isControllingPrincipal": true,
                "isPrimaryContact": true,
                "ownerEmail": "[email protected]",
                "maskedDriverLicenseNumber": "6788",
                "userId": "e29e36d3-5205-4c23-b5d4-f671b0b9ae28"
            }
        ],
        "agreementAcceptances": {
            "globalStatus": "created",
            "principalList": [
                {
                    "principalId": "1db46ac1-a109-4f20-ab7f-905374b162b3",
                    "name": "Sydney Grimes",
                    "email": "[email protected]",
                    "status": "pending",
                    "ownership": 100,
                    "order": 1
                }
            ]
        },
        "paymentMethods": {
            "onlinePaymentsPercentage": 100,
            "inStorePaymentsPercentage": 0,
            "keyedInPaymentsPercentage": 0
        },
        "motoQuestionnaire": {
            "productAdvertisementChannels": "Google Ads, Facebook Ads",
            "orderPlacementChannel": "Online",
            "productAndServiceDeliveryChannel": "UPS / Fedex",
            "refundPolicyDescription": "30 days full refund",
            "fulfillmentHouseInfo": {
                "fulfillmentHouseServiceName": "FullHouse LLC",
                "fulfillmentHousePhoneNo": "(888)-888-8888"
            }
        },
        "processingEquipment": {
            "equipment": [],
            "gateways": [],
            "onlinePaymentMethods": []
        },
        "securityInfo": {
            "creditCardDataStoredElectronically": [],
            "isPciCompliant": true,
            "priorDataBreachExplanation": null
        }
    }
}

Pay close attention to the "applicationSummary.applicationReadiness" properties:

  • state property: The value for this property can be either "ready" or "missing_information". When the property value is "missing_information", then the "missingInputs" array will contain the properties that you need to still collect from your merchant for the application to be considered ready.
  • missingInputs array: This array will contain a list of properties for which you still need to collect information. The value for this property can be either "ready" or "missing_information". When the property value is "missing_information", then the "missingInputs" array will contain the properties that you need to still collect from your merchant for the application to be considered ready. Once you collect the missing information you can update the application using our Update Application API. The API reference doc can be found in https://docs.gettrx.com/reference/update-an-application

Updated 6 months ago