Embedded Onboarding UI

Overview

The PayEngine 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"
}'
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. PayEngine 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 PayEngine Merchant ID (merchant_id).
The HMAC generated will be passed to the client-side snippet to a property called 'hash'.
Node.js
Rail Ruby
Django (Python)
PHP
Other
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
merchant_id_hash = OpenSSL::HMAC.hexdigest(
'sha256', # HASH FUNCTION
'YOUR_SECRET_KEY', # SECRET KEY (KEEP SAFE!)
<merchant_id> # REPLACE WITH MERCHANT ID
) # PASS THIS TO FRONT-END
import hmac
import hashlib
merchant_id_hash = hmac.new(
'YOUR_SECRET_KEY', # SECRET KEY (KEEP SAFE!)
<merchant_id>, # REPLACE WITH MERCHANT ID
digestmod=hashlib.sha256 # HASH FUNCTION
).hexdigest() # PASS THIS TO FRONT-END
merchant_id_hash = hash_hmac(
'sha256', // HASH FUNCTION
<merchant_id>, // REPLACE WITH MERCHANT ID
'YOUR_SECRET_KEY' // SECRET KEY (KEEP SAFE!)
); // PASS THIS TO FRONT-END
Generate an HMAC with SHA256 whenever a user logs into your app. Most web frameworks will have a method or library to help you do this. You'll need your app’s private key and Merchant ID.
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 PayEngine 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": "PayEngine 222333 111",
"address_street": "Address",
"address_unit": "suite",
"address_city": "HCM",
"address_state": "AZ",
"address_zip": 15454
},
"dba": {
"name": "PayEngine",
"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 protected]",
"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 protected]",
"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: "PayEngine 222",
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": {
...
}
}