Merchant onboarding APIs

This guide provides steps to use APIs to onboard and optionally auto submit the application for underwriting immediately.

This platform provides a fast and secure way to quickly onboard a merchant via Embedded Onboarding UI. If Auto Submission is enabled for your account, the embedded UI takes care of presenting the contract documents to your merchants and automatically submits the application to the processor to start the underwriting process immediately.

However, if you decides to build your own onboarding UI using the Onboarding APIs, you can still take advantage of the auto submission and digital signature capture feature.

Please note that auto submit/signature capture needs to be enabled for your account before you can use it via onboarding APIs. Please contact the support team if you need help enabling this feature.

Creating a new merchant

Onboarding process begins by creating and obtaining a merchant ID. This step ensures that merchant account is only created through server-to-server communication before any embedded or custom onboarding form is presented to your merchants.

You can also use this step to pre-fill information which can simplify onboarding process for your merchants. For example, based on your product offerings, you can set fee schedule for your merchants here instead of manually changing it later in the partner console.

// Creating a merchant - simlified request
{    
    "name": "Merchant's Name",
    "email": "<merchant's_email>"
}

// Creating merchant while setting country and fee schedule
{
    "name": "Merchant's Name",
    "email": "<merchant's_email>",
    "business_type": {
        "country": "CA"
    },
    "fee_schedule_id": "e7b4ef7d-0696-4a6c-81cd-6ace87ba6123"   
}

Providing a merchant's website URL while creating a merchant

There are use cases when you want your merchants' website prefilled with a URL before they even interact with the onboarding form. You can provide any business detail to be prefilled for example website.

// Creating a merchant with prefilled website information
{
    "name": "Merchant's Name",
    "email": "<merchant's_email>",
    "business_details": {
        "website": "http://www.test.com"
    }
}

Updating a Merchant

Once you have merchant ID created, you can use update API to fill onboarding application. Please refer to our comprehensive API documentation to learn more about how to update merchant application.

It is highly recommended to use validation feature of the update API or use Onboarding Application Validation API before submitting for underwriting. This API provides useful validation information which you can display in your UI as well.

Submitting for Review

Once your onboarding application is updated (and optionally validated) you can submit it for review and start the underwriting process.

• When you submit an application it is automatically moved to in_reivew state for you to review in the partner console. You can also set submitted_to_pe explicitly in your API call to skip the review and go straight to underwriting.

• If you have auto submit feature enabled, the app is automatically submitted to the processor after merchant digitally sign the agreement.

Example of directly submitting the application to the processor.

curl -X POST https://<payengine-partner-server>/api/merchant/:id/submit \
  -H 'Authorization: Basic <partner_private_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "status": "submitted_to_pe"
      }'

Getting the signing URL

Please note that auto submit/signature capture needs to be enabled for your account before you can use it via onboarding APIs. Please contact the support team if you need help enabling this feature.

If Auto Signature is enabled in our account, submitting the app will respond back with a document link as in the following example code.

Submit Request

curl -X POST https://<payengine-partner-server>/api/merchant/:id/submit \
  -H 'Authorization: Basic <partner_private_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "status": "submitted_to_pe"
      }'

Response with signature URL

The signing_url can be used to present the documents to your merchants to start the digital signature process.

Our recommended way is to display signing URL's contents in an iframe within your application so it remains a fully integrated and seamless experience for your merchants.

Displaying documents in an iframe

const iframe = document.createElement("iframe");
iframe.src = "<signing_url_from_submit>";
iframe.id = "payengineSigningIframe";
iframe.width = "80%";
iframe.height = "80%";
iframe.style = "position: fixed; z-index: 10; top: 10%; left: 10%; background: #FFF; border: #555 1px solid;"
document.querySelector("body").append(iframe);

The example code above renders the content of signing_url in an iframe and displays it as the top element of your application window. Once rendered, this iframe will post a message to the parent window to notify the results of the signing process which can be used to dismiss the iframe and execute the desired workflow in your application.

Listening to events

When merchants successfully sign or decide to cancel (do it later), a message will be sent to the parent window that hosts the iframe. This message can be observed to perform subsequent actions for example dismissing the iframe and refreshing the merchant status.

const signingMessageHandler = (event: MessageEvent) => {
    if (event.origin === '<payengine-api-server>') {
        const { event: childEvent, reason } = event.data
        if (childEvent === 'PF_SIGNATURE_COMPLETED') {
            // remove the signing iframe from DOM
            document.getElementById("payengineSigningIframe").remove();
            // perform refreshing merchant or update UI...
            switch (reason) {
                case 'complete':
                    // merchant successfully signed
                    break;
                case 'decline':
                    // merchant declined to sign
                    break;
                case 'cancel':
                default:
                    // merchant canceled signature process (do it later)
                    break;
            }
        }
    }
}

Browser compatibility - Some old browsers don't support postMessage with cross-domain, i.e. Internet Explorer 8 for example.

Content Security Policy - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src

Handling Onboarding Webhooks

The onboarding APIs also trigger Webhooks to notify milestone events of a merchant onboarding process. For detail information about Webhooks please see our developer guide.

You can expect to get the following events during merchant onboarding process.

Webhook event: MERCHANT_CREATED

Webhook Payload Example

{
  event_uid: '220489c0dfa263d19ee1796973cdc9f6',
  event: 'MERCHANT_CREATED',
  data: {
    id: 'c404d923-226f-4aae-92da-22c1ef370434',
    account_id: 'e90c1de6-4e87-4c9e-bcbc-c535d6e349ec',
    merchant_id: 'c404d923-226f-4aae-92da-22c1ef370434'
  }
}

Webhook event: MERCHANT_STATUS_CHANGED

Webhook Payload Example

{
  event_uid: '43ab1219e4eab0809528a211c115f099',
  event: 'MERCHANT_STATUS_CHANGED',
  data: {
    id: 'c404d923-226f-4aae-92da-22c1ef370434',
    status: 'in_review',
    account_id: 'e90c1de6-4e87-4c9e-bcbc-c535d6e349ec',
    merchant_id: 'c404d923-226f-4aae-92da-22c1ef370434'
  }
}

Webhook event: MERCHANT_SIGNING_COMPLETED

Webhook Payload Example

{
  event_uid: '75426b45fb87fc7cdaa81318dd3507f8',
  event: 'MERCHANT_SIGNING_COMPLETED',
  data: {
    account_id: '3cab79a6-31bd-43e6-9a0c-e5870b18fa38',
    merchant_id: 'b4663989-4256-4027-88da-d6ad3e55ae80'
  }
}

Webhook event: MERCHANT_SIGNING_CANCELLED

Webhook Payload Example

{
  event_uid: 'a295035381021a4929e1517d41d35a80',
  event: 'MERCHANT_SIGNING_CANCELLED',
  data: {
    account_id: '3cab79a6-31bd-43e6-9a0c-e5870b18fa38',
    merchant_id: '3d8b4959-a5d8-456f-a02a-8b462a6600d2'
  }
}

Webhook event: MERCHANT_SIGNING_DECLINED

Webhook Payload Example

{
  event_uid: '7f0f16825bd05f791b9b76480385a8c9',
  event: 'MERCHANT_SIGNING_DECLINED',
  data: {
    account_id: '3cab79a6-31bd-43e6-9a0c-e5870b18fa38',
    merchant_id: '3d8b4959-a5d8-456f-a02a-8b462a6600d2'
  }
}