Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Airwallex gateway
Hold & convert funds
Connected accounts
Connected accounts overviewOnboard connected accounts
KYC and onboarding
Embedded KYC componentHosted onboarding
Native API
Simulate connected account status transition
Handle KYC Request for Information (RFI)
KYB and onboarding
Move funds between accounts
Compliance and Outsourcing requirements
Error codes

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 a connected account. Specify the account_id of the connected account (from Step 1) for which you are creating the flow , and the hosted flow template id as provided by Airwallex.

A successful request will return a hosted flow instance ID and the return URL to redirect the end user when onboarding is complete.

Make sure to save the hosted flow instance ID mapped to the connected 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

Explicitly authorize the user to access the created hosted flow instance. Redirect the user to the url link returned in the authorization response.

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 onboarding flow without completing the form. If the session has expired, we will show a session prompt that lasts for 60 seconds before we logout the user 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 the POST /api/v1/hosted_flows/{hosted_flow_instance_id}/authorize endpoint 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 via webhooks. See connected account 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