Hosted Onboarding
Hosted KYB is the recommended solution for platforms to activate payment methods for customers without having to build your own full-fledged payment activation form around Airwallex APIs.
Our hosted form dynamically takes care of collecting required information to activate payment methods, customized by business scenario and payment methods. You’ll directly leverage our UX optimizations for error handling. You can also customize the visual appearance of the onboarding form to reflect your brand.
Through Hosted Payment Method Activation, a platform can
- Via an API, retrieve a Hosted flow link unique to a connected account
- Direct the end user who clicks on the link into an Airwallex-hosted environment to complete a white-labeled payment activation form
- After the payment activation form is complete, the end user is automatically redirected back into your environment (or to any return URL of choice)
Before you begin
- Contact your Airwallex Account Manager to:
- Enable connected account hosted using Hosted flow. The Account Manager will create a hosted flow template and will provide you with the template open ID (to be used in Step 2).
- Customize your hosted flow main landing page for business name, logo and color. Note that the customized logo will appear on all hosted flow pages.
- Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
- You must be integrated to use Airwallex native API for all other funds flow and payments control.
Step 1: Create an account and pre-fill information
POST /api/v1/accounts/create
Handle response and error logic. Make sure to save the account_id for this account from the response.
Step 2: Create hosted flow
POST /api/v1/hosted_flows/create
Create a hosted flow instance for an account. Specify the account_id of the connected account for which you are creating the flow (from Step 2), and the hosted flow template id (from Step 1).
Request
Response
From the response, make sure to save the hosted flow id mapped to the account.
Error responses could include:
- 400 (template not found, account id not found)
- 403 (not authorized for this action/account, account status is SUSPENDED – that is, disabled or failed KYC)
- 500 (server error)
Step 4: Handle re-entry
The user may exit the hosted onboarding form without finishing and attempt to re-enter later. If the user has not exited but the session expired, we will show a session prompt that lasts for 60 seconds before we logout the user with error code TOKEN_EXPIRED.
In order to handle re-entry,
- Check if a saved hosted flow instance id for the account exists (from Step 3).
- If the account has a saved hosted flow, re-authorize the user: Call the POST /api/v1/hosted_flows/{id}/authorize endpoint to retrieve a link with a new authorization code
- Redirect the user to the new url from the response.
Error handling
| Error code | Message | Next steps |
|---|---|---|
TOKEN_EXPIRED | Authorization code has expired | |
UNAUTHORISED | Unauthorised. Invalid token also results in this error | |
INVALID_ACTION_STATUS | Action of hosted flow instance has a status that is not valid to operate on | Unrecoverable error. Example is the account’s KYB application is rejected. |
FLOW_INSTANCE_NOT_FOUND | Hosted flow instance is not found | Create a new hosted flow instance as described in Step 2 |
SUBMIT_FAILED | KYB submission failure | Retry submission if network error or contact Airwallex support. |
UNKNOWN | Unidentified errors | Contact Airwallex support |