Embedded Onboarding UI

Overview

The Embedded Onboarding Forms allow our partners to easily collect necessary merchant onboarding details from their users and submit them for the underwriting process.

The Embedded Onboarding UI requires only a minimal HTML/Javascript code and can be embedded onto any part of your web applications where you would like users to register for payments within your system.

Advantages of using Embedded Onboarding UI

Instantly create customized onboarding forms that adhere to security requirements. Our servers intercept the sensitive data you don't want deal with (social security numbers, EIN, other merchant related info) and replace it with aliased versions for your own data keeping while securing the original data in our vault and submitting it to the acquiring side.

The following shows rendered onboarding form examples using our Embedded Onboarding UI technology.

Before starting the following integration You will need your public and private keys from your partner console account.

Implementing Embedded Onboarding UI

1. Create a new merchant account

In order to keep the merchant creation process at parity with the customer profiles within your platform (and before the onboarding form can be shown to a specific customer), you need to make a call from your backend environment to initialize and associate a new merchant profile within our system. This is necessary because the browser is not a secure environment and should never contain your access secret (which is required to invoke our API).

curl -X POST https://<payengine-partner-server>/api/merchant \
  -H 'Authorization: Basic <partner_private_token>' \
  -H 'Content-Type: application/json' \
  -d '{
          "external_id": "2ljk534jh5v3h456klj245",
          "email": "<merchants_email>",
          "name": "Merchants Name",
          "business_type": {
              "country": "CA"
           },
          "fee_schedule_id": "e7b4ef7d-0696-4a6c-81cd-6ace87ba6123"   
      }'

The above call will create a new merchant profile within our system and provide you with an internal ID from our system, so you can use it for presenting the onboarding form for this merchant.

Note: The merchant_id obtained from the API call above is not an active merchant id until the onboarding application is submitted and approved by the acquiring processors.

2. Authenticating Secure Setup (required for production, optional in sandbox)

Your customer portal must be behind some kind of user authentication in order to safely show customers their information. This platform authenticates users with an HMAC hash generated for the logged-in user. This allows us to work with any authentication system.

Your code for generating an HMAC for your app must be placed in the back-end of your application. Grab the snippet from the developer dashboard to add to your server. You may generate the HMAC with the user's platform Merchant ID (merchant_id).

The HMAC generated will be passed to the client-side snippet to a property called 'hash'.

const crypto = require("crypto");
const merchant_id_hash = crypto.createHmac(
    "sha256",
    "YOUR_SECRET_KEY" // SECRET KEY (KEEP SAFE!)
).update(<merchant_id>).digest("hex") // PASS THIS TO FRONT-END

Keep your private key safe! Never commit it directly to a public repository, client-side code, or anywhere a third party can find it.

3. Adding JS to your onboarding page

To add JS to your onboarding page, include our JavaScript library in your host page:

<head>
  <script src="https://<payengine-partner-server>/js/wc/js/payengine.min.js?key=<your-public-api-key>"></script>
</head>

Then copy the following HTML snippet into your custom page:

<style id="onboarding-styles">

  .pf-field {
    font-family: '"Helvetica Neue", Helvetica';
    box-sizing: "border-box";
    border: "#CCC 1p solid";
    color: "#31325F";
    padding: "0 10px";
  }
  .pf-field::placeholder {
    color: "#CFD7E0";
  }
  
  .pf-button-next {
    background-color: red;
  }
  
  .pf-button-back {
    background-color: grey;
  }
   
</style>
 
<pay-engine 
    id="pf-onboarding"
    type="boarding" 
    merchant-id="<payengine_merchant_id>" 
    hash="<HMAC_hash_of_payengine_merchant_id>"
    css="#onboarding-styles"
></pay-engine>

In the sandbox environment, you can leave the hash property empty.

To see the full list of specs, please refer to the API documentation with your developer portal account.

4. Visit the merchant onboarding form

If everything in the steps above was set up correctly, you should be able to view the implemented form from within your application. For testing convenience, while in sandbox mode, the form will include a helper button to help test the form without much effort.

5. View merchant status and update any details

Once the form has been submitted, you may review all the details from your partner details by visiting the Merchants page (pictured below).

6. Set merchant fee schedule

You can review and override any of the merchant fee schedules before submitting them for review.

To create a merchant fee schedule template, navigate to Account / Fee Schedules section from your partner admin, and click to create a new schedule.

To select specific fee schedules for incoming merchants, edit the application from the merchants list screen from within the partner portal, and click on the fee schedules.

7. Submit merchant for underwriting

As the final step to submit the merchant to our acquiring processors, you can manually submit the application for the process after your review. Upon approval from the acquiring processor, you can activate their gateway and start processing transactions.

Custom props and methods

1. Configurable props

hidden-sections Determinate one or some sections should be hidden from the UI. Passed as a comma-separated string. Available sections:

  • BusinessInformation

  • OwnerOfficerInformation

  • ProcessingInformation

  • BankingInformation

  • PatriotAct

  • ACHAddendum

  • MerchantSiteSurvey

Example:

<pay-engine
    type="boarding" 
    merchant-id="8e85fe03-d521-4e52-8404-0fb8fa11c4fb" 
    hidden-sections="OwnerOfficerInformation,MerchantSiteSurvey">
</pay-engine>

2. Methods

populateData(data: any) => void Populate the existing data into onboarding form.

Example:

<pay-engine
    id="pf-boarding"
    type="boarding" 
    merchant-id="8e85fe03-d521-4e52-8404-0fb8fa11c4fb"></pay-engine>
    
<script>
window.onload = function() {
    var prePopulatedData = {
      "business_details": {
        "legal": {
          "name": "Los Angeles Express",
          "address_street": "Address",
          "address_unit": "suite",
          "address_city": "HCM",
          "address_state": "AZ",
          "address_zip": 15454
        },
        "dba": {
          "name": "LA Express",
          "address_street": "Address",
          "address_unit": "suite",
          "address_city": "HCM",
          "address_state": "AZ",
          "address_zip": 15454
        },
        "dba_same_as_legal": true,
        "business_phone_no": "7526463989",
        "email": "email@example.com",
        "business_age_years": 1,
        "business_age_months": 2,
        "business_description": "Description of products or services sold",
        "how_products_delivered": "Directly to consumer's home",
        "when_product_received": "2-3 business days",
        "return_policy": "Return before 30 days",
        "tax_exempt": false,
        "type_of_tax_id": "SSN",
        "tax_identification_number": "353535355",
        "accepted_transaction_types": [
          "CC_DC",
          "ACH"
        ],
        "number_of_locations": "1",
        "company_annual_revenue": 1000000,
        "place_of_issuance": "CA",
        "aoi_day": 20,
        "aoi_month": 2,
        "aoi_year": 2020,
        "how_many_days": "2-3 business days",
        "b2b_percentage": 70
      },
      "credit_card_processing": {
        "card_swiped": 25,
        "manually_keyed_cp": 25,
        "manually_keyed_cnp": 25,
        "ecommerce": 25,
        "accept_cc_before": true,
        "previous_processor_name": "CC Processor",
        "avg_transaction_amount": 25,
        "total_monthly_sales": 10000,
        "highest_transaction_amount": 25,
        "frequency_ticket_per_year": "25",
        "qualified_processing_method": "EDCRetail"
      },
      "ach_processing": {
        "max_check_amount": "1000",
        "avg_check_amount": "30",
        "max_monthly_transaction_amount": 25,
        "min_monthly_transaction_amount": 25,
        "max_daily_transactions_count": 25,
        "max_monthly_transactions_count": 25,
        "total_annual_amount": 25,
        "avg_number_checks_monthly": "3000",
        "est_monthly_check_volume": "30000",
        "web": 25,
        "tel": 25,
        "ppd": 25,
        "ccd": 25
      },
      "owner_officers": {
        "current_index": -1,
        "officers": [
          {
            "first_name": "John",
            "middle_name": "",
            "last_name": "Doe",
            "ownership": 75,
            "address_same_as_legal": false,
            "address_street": "Main Street",
            "address_unit": "",
            "address_city": "Los Angeles",
            "address_state": "CA",
            "address_zip": "90245",
            "email": "email@example.com",
            "phone_no": "3494262452",
            "birth_month": 2,
            "birth_day": 28,
            "birth_year": 1990,
            "ssn": "353535355",
            "title": "CEO",
            "signing_app": true,
            "personal_guarantor": true,
            "country_of_citizenship": "USA"
          }
        ]
      }
    };
    document.getElementById('pf-boarding').populateData(prePopulatedData);
}
</script>

Please refer to Onboarding API specs for a working example and data structure.

3. Events

<pay-engine id="onboarding" merchant-id="ea0e0ae6-aa42-48da-b801-0106facf1e37" type="boarding"></pay-engine>

<script type="application/javascript">
    document.getElementById('onboarding').addEventListener('stepChange', function(e) {
        console.log(e.detail)
    })
    document.getElementById('onboarding').addEventListener('submitted', function(e) {
        console.log(e.detail)
    })
</script>

ready

The ready event occurs when the onboarding component has been fully loaded.

Example: pre-fill onboarding data after the component has been loaded

document.getElementById('onboarding').addEventListener('ready', function() {
    this.populateData({
        business_details: {
            legal: {
                name: "LA Express",
                address_street: "Address",
                address_unit: "suite",
                address_city: "HCM",
                address_state: "AZ",
                address_zip: 15454
            }
        }
    })
})

stepChange

Execute event while user navigates through onboarding steps

Example payload on stepChange event:

{
    "step": "BusinessDetails",
    "data": {
        ...
    }
}

Possible step names:

  • BusinessType

  • BusinessDetails

  • YourDetails

  • CreditCardProcessing

  • ACHProcessing

  • BankDetails

  • DocumentAttachments

  • Submission

submitted

This event is triggered when user submits the application for review

Example payload on submitted event:

{
    "submitted": true,
    "data": {
        ...
    }
}
PreviousOnboarding/Payments Application WorkflowNextMerchant onboarding APIs

Last updated