Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Banking as a ServiceSupported regions and currencies
Get started
Connected accounts
Connected accounts overviewKYC and onboarding
Embedded KYC componentHosted onboarding
Native API
Simulate connected account status transition
Handle KYC RFI
Onboard multiple connected accountsMove funds between accounts
Compliance and Outsourcing requirements
Error codes
Test and go live

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:

  1. Retrieve a secure, short-lived hosted flow link unique to each connected account via an API
  2. Direct the end user who clicks on the link into an Airwallex-hosted environment to complete a white-labeled onboarding form
  3. 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

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.

Example 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 (template not found, account_id not found)
  • 403 (not authorized for this action/account, account status is SUSPENDED, i.e., disabled or failed KYC)
  • 500 (server error)
Example request
Example response

Step 3: Authorize the user into the hosted flow

Call Authorize the flow API using the hosted flow instance id (returned in the previous request) to authorize the URL. The authorized url returned in the authorization response is short-lived so it’s highly recommended that you redirect the customer as quickly as possible.

The customer can choose to respond to any of the open RFIs displayed on the page.

Error responses could include:

  • 400 (hosted flow already finished)
  • 403 (not authorized for this action/account/flow)
  • 404 (hosted flow instance ID not found)
  • 500 (server error)
Example request
Example response

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:

  1. Check if a saved hosted flow instance ID for the account exists (from Step 2).
  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.
  3. 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 codeMessageNext steps
TOKEN_EXPIREDAuthorization code has expiredRe-authorize the user (see Step 3) using the saved hosted flow instance ID
UNAUTHORISEDUnauthorised. Invalid token also results in this errorAuthorize the user (see Step 3) using the saved hosted flow instance ID
INVALID_ACTION_STATUSAction of hosted flow instance has a status that is not valid to operate onUnrecoverable error. For example, the account’s KYC application is rejected or RFI status is closed.
FLOW_INSTANCE_NOT_FOUNDHosted flow instance is not foundCreate a new hosted flow instance as described in Step 2
SUBMIT_FAILEDKYC submission failureRetry submission if network error or contact Airwallex support.
UNKNOWNUnidentified errorsContact Airwallex support
On this page