Embedded KYB component
The Embedded KYB component is a pre-built UI element that lets your connected accounts to complete the KYB (Know Your Business) onboarding process to start receiving funds using the Airwallex payment gateway. Instead of building your own native onboarding flow, you can now deliver a conversion-optimized, frictionless onboarding experience that leverages the following features:
- Dynamically take care of KYB and compliance via Airwallex’s UI
- Leverage Airwallex’s conversion-optimized flow, including STP (Straight Through Processing) after submission
- Customize the visual appearance to match the look and feel of your platform website
- Tailor user interactions against the component's lifecycle
To view the onboarding experience offered by the Embedded KYB component, go to the Airwallex demo site .
This page describes how to embed the KYB component into your page to start onboarding connected accounts for payments acceptance.
KYB is only required if your connected accounts will be onboarded as Merchant-Of-Record, which depends on your payments gateway model of choice.
How it works
The diagram below depicts the information flow in an Embedded KYB component integration.
Before you begin
- Ensure your connected accounts have already applied for general onboarding (KYC) else you will receive errors when trying to access the KYB component.
- Contact your Airwallex Account Manager to enable KYB onboarding using Embedded Components.
- Depending on your Airwallex payment gateway model, provide your Account Manager with a list of payment methods you want to make available to your connected accounts.
- Obtain your access token by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
- Explore the
@airwallex/components-sdkJavaScript client library reference to familiarize yourself with the Embedded KYB component methods, parameters, and properties. - Install the package
- Using Yarn or NPM
yarn add @airwallex/components-sdknpm install @airwallex/components-sdk
- Using CDN
<script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
- Using Yarn or NPM
Step 1: Create a connected account for KYB
Call Create a connected account API by providing the required fields in the request. Note that the terms of data usage have to be agreed by the connected account before proceeding with the API request.
Handle response and error logic. Make sure to save the account_id returned in the response.
Optionally, you can update the account by calling Update a connected account API to pre-fill the information.
Step 2: Initialize the components web SDK
First, you will need to import the components-sdk and then initialize the environment. For details, see Initialize components SDK .
Set up the server for authentication
When the user, i.e., the connected account holder, begins the onboarding process, you will need to get an authorization code to authorize them into the Embedded KYB workflow. Always get authorization code on the server side, a trusted environment. This prevents malicious users from being able to alter the scope.
When the onboarding page loads, on your server, call Authorize a connected account API by providing the required fields in the request.
scope: Indicates the resources your application is allowed to access. For Embedded KYB onboarding, you must providew:awx_action:kybas the scope.code_challenge: Generate a challenge token together with thecode_verifierusing the S256 generation method as described in RFC 7636 Section 4.code_challenge=BASE64URL-ENCODE(SHA256(ASCII(code_verifier))). Use a third-party package to generatecode_verifierandcode_challengeor use the following code example in Javascript.
The authorization_code is returned in the response, which you should then return to the client side as authCode in order to initialize the SDK.
Step 3: Add the Embedded KYB component to your page
To embed the onboarding flow into your page, you will need to create an empty container, create the onboarding component and then mount the element to the container.
Define the KYB onboarding container
First, create an empty container div with a unique id in your payments KYB page. Airwallex inserts an iframe into this div on mounting the element.
Create the Embedded KYB component
To create the onboarding component, call createElement(type, options) and specify the type as paymentsKyb. This method creates an instance of an individual component. Components are rendered as iframes.
You can also pass options in createElement() to overwrite styles and other functions. All properties are optional. For details, see Create an Element .
Mount the element
Call element.mount() with the id of the div container to mount the element to the DOM. This builds an embedded onboarding workflow. The element should only be mounted once in a single onboarding flow.
For all the other methods supported on this component, see Element object methods .
Handle the ready event
Add the ‘ready’ event listener to ensure the KYB onboarding component is rendered. It's recommended that you show a loading state UI before receiving the ‘ready’ event. You can also use the user’s kybStatus result, which represents the account’s KYB onboarding status, and render different status pages accordingly.
Step 3: Handle the response
Add success and error event listeners to handle error and success events received from Airwallex.
If no error occurred, display a message that onboarding was successful. If SCA fails with an error, display the appropriate message to your end user so they can take action and try again. See Element events .
See table below for the common error codes and recommended next steps.
| Error code | Error message | Next steps |
|---|---|---|
| INIT_ERROR | No <parameter> provided | Check the params table for required init options. |
| INIT_ERROR | Failed to authorize | Confirm that the clientId, env, codeVerifier and authCode passed in the init() function are valid. |
| INIT_ERROR | Auth timeout | Please check if your network connection is stable. If so, please contact Airwallex support. |
| UNAUTHORIZED | Failed to refresh token | The refreshToken might be expired (currently 1 hour). Please redo the entire flow to get a new authCode and initialize the SDK, and then create the element again. |
| CREATE_ELEMENT_ERROR | Please init() before createElement() | Please confirm you have correctly loaded the SDK script using the init() function from our package or the CDN link. |
| CREATE_ELEMENT_ERROR | CreateElement with type <type> not supported | Check the supported types . |
| MOUNT_ELEMENT_ERROR | Cannot find element with dom element id: <id> | Please check if the container dom id or the dom element passed in the mount() function is valid. |
| PERMISSION_DENIED | User does not have access permission. | Account is not eligible to access Airwallex Online Payments. Please check that the account has applied for general onboarding (KYC). For further inquiries, please contact Airwallex support. |
| SUBMIT_FAILED | Internal API error: Failed to submit form. | Please retry or contact Airwallex support. |
| UNKNOWN | Unknown error | Please retry or contact Airwallex support. |
| API_ERROR | <API_name> API error | Error occurred when calling internal API. Please retry or contact Airwallex support. |
| - (Console message only) | Please initialize Airwallex platform onboarding SDK | Please confirm if you have correctly loaded the SDK script using the init() function from our package or the CDN link. |
Test your integration
You may test your integration for various success and error scenarios in the demo environment and then go live in the production environment. Contact your Airwallex Account Manager for test account details.
To trigger SDK errors during testing, use these instructions.
| Error Code | How to trigger |
|---|---|
| INIT_ERROR | Call init() function with unsupported values for options, e.g., await init({env: 'other'}) where other is not supported |
| UNAUTHORIZED | Internal error, unable to trigger |
| AUTH_TIMEOUT | Block your network |
| CREATE_ELEMENT_ERROR | Call createElement() function with unsupported element type, e.g., createElement('wrong_type') |
| MOUNT_ELEMENT_ERROR | Call mount() method with a non-existent div id. e.g., element.mount('nonexistent-div-id') |
| SUBMIT_FAILED | Internal error, unable to trigger |
| UNKNOWN | Internal error, unable to trigger |
| API_ERROR | Block your network |
FAQ
How do I customize the embedded component?
Contact your Airwallex Account Manager to enable customization of the look and feel in line with your brand. Your Account Manager will assist you in generating a theme schema, which can be passed into the component upon initialization.
The theme schema includes:
- Colors: You can recolor the component by specifying a set of 10 colors which makes up a color gradient. The colors can be in one or multiple tones.
- Component-level configuration
- Typography
What are the recommended dimensions for the component?
The component is responsive and designed for a variety of common screen resolutions.
However, the suggested web dimensions for responsiveness are:
- Width: 500px
- Height:
- 2000px to avoid a scroll bar
- 750px with a scroll bar
How do I handle re-tries?
If a user exits the onboarding component then tries to re-enter the details later, you can handle re-entry based on the user’s onboarding status. Use kybStatus from the ‘ready’ event fired when the component is rendered (see Handle the ready event).
INITstatus: The user will re-enter the onboarding workflow again, and automatically be taken to where they last left off.PENDING_REVIEW/IN_REVIEW/ACCEPTED/REJECTEDstatus: The account has already completed the onboarding workflow. You should render different status pages according to thekybStatusresult. If you do not handle it, we will show default submitted/success/failure pages accordingly.
| KYB Status | Description |
|---|---|
| INIT | An initial status before KYB information is submitted by the customer. The application is currently in progress and awaiting completion. Please provide necessary reminders to complete the submission. |
| PENDING_REVIEW | KYB information was submitted successfully. However, the application is currently in a state of pre-processing and is pending review. This is a temporary status, and our team will promptly review the application. Refrain from taking any further action at this moment. |
| IN_REVIEW | The customer successfully submitted KYB information. The application is in review. No further action is required at this stage. Please await the outcome of the review. |
| REJECTED | The KYB application has been rejected. |
| ACCEPTED | The KYB application has been approved, and the customer has accepted one of the reserve options offered. To retrieve the final reserve on the account, use the event reserveOptionsSelected with event data {selected: UserReserveSelection[]}. |