Hosted Onboarding
Hosted onboarding enables you as a platform to redirect end users to an Airwallex-hosted web form to complete onboarding onto the platform account. This means you can onboard customers without having to build your own full-fledged onboarding form using Airwallex APIs.
Airwallex's hosted form dynamically takes care of collecting required KYC information, customized by country or account type. You’ll directly leverage our UX optimizations for conversion rate and localization. You can also customize the visual appearance of the onboarding form to reflect your brand.
The hosted flow includes these three simple steps:
- Retrieve a secure, short-lived hosted flow link unique to each connected account via an API
- Direct the end user who clicks on the link into an Airwallex-hosted environment to complete a white-labeled onboarding form
- After the onboarding form is complete, the end user is automatically redirected back into your environment (or to any return URL of your choice as provided when creating the hosted flow instance).
Explore the end user experience of completing the hosted flow on the demo environment .
Before you begin
- Contact your Airwallex Account Manager to:
- Enable connected account onboarding 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.
- The connected accounts you are onboarding must be business accounts (not individuals).
Step 1: Create a connected account for KYC
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: Create a hosted flow instance
Create a hosted flow instance for an account, your own account or a connected account. Specify the account_id for which you are creating the flow and the hosted flow template id as provided by Airwallex. You will also need to specify a return_url to which the customer will be redirected once the flow is complete.
A successful request returns a hosted flow URL (url) and a hosted flow instance ID (id). The URL must not be shared with the customer until it’s authorized by you to ensure that it’s only intended for this customer.
Make sure to save the hosted flow instance ID mapped to the account.
Error responses could include:
- 400 (
templatenot found,account_idnot found) - 403 (not authorized for this action/account, account status is SUSPENDED, i.e., disabled or failed KYC)
- 500 (server error)
Step 4: Handle session timeout
Session timeouts may occur due to inactivity or if the user exits the hosted flow without completing the form. If the session has expired, we will show a session prompt that lasts for 60 seconds before we log the user out with error code TOKEN_EXPIRED.
The user may return to the form to complete the information after a session expiry. To handle this scenario:
- Check if a saved hosted flow instance ID for the account exists (from Step 2).
- If the account has a saved hosted flow, re-authorize the user (Step 3). Call Authorize the flow API to retrieve a link with a new authorization code.
- Redirect the user to the new URL from the response.
Step 5: Handle response
Listen for status changes to the account/transaction via webhooks. See webhook events.
Error handling
| Error code | Message | Next steps |
|---|---|---|
TOKEN_EXPIRED | Authorization code has expired | Re-authorize the user (see Step 3) using the saved hosted flow instance ID |
UNAUTHORISED | Unauthorised. Invalid token also results in this error | Authorize the user (see Step 3) using the saved hosted flow instance ID. If the user has Airwallex web app access, please try opening the hosted flow link in incognito mode. |
INVALID_ACTION_STATUS | Action of hosted flow instance has a status that is not valid to operate on | Unrecoverable error. For example, the account’s KYC application is rejected or RFI status is closed. |
FLOW_INSTANCE_NOT_FOUND | Hosted flow instance is not found | Create a new hosted flow instance as described in Step 2 |
SUBMIT_FAILED | KYC submission failure | Retry submission if network error or contact Airwallex support. |
UNKNOWN | Unidentified errors | Contact Airwallex support |