Hosted flow

To integrate the hosted flow for onboarding verification, complete the steps in this document. Onboarding verification, previously referred to as Know Your Customer (KYC), is the process by which Airwallex verifies the identity of a connected account holder. The hosted flow redirects account holders from your platform to an Airwallex-hosted form to complete onboarding. It dynamically collects identity information based on the account holder's country and account type, and supports visual customization to reflect your brand. This method supports business accounts only.

To preview the end user experience, see the demo environment .

Before you begin

Ensure you have the following before you start:

• Hosted flow onboarding enabled on your platform account, including a hosted flow template open ID (the unique identifier Airwallex provides for your hosted flow template). Contact your Airwallex Account Manager to request access and any customization of your landing page (business name, logo, and color).
• An access token API for your Airwallex account.

Create a connected account

Call Create a connected account API and provide the required fields in the request. The connected account must agree to the terms of data usage before the API request is made.

Example request

1curl -X POST https://api-demo.airwallex.com/api/v1/accounts/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "primary_contact": {
6      "email": "[email protected]"
7    },
8    "account_details": {
9      "business_details": {
10        "business_name": "Example Company"
11      }
12    },
13    "customer_agreements": {
14      "agreed_to_terms_and_conditions": true,
15      "agreed_to_data_usage": true
16    }
17  }'

Save the account_id returned in the response and implement error handling.

Optionally, call Update a connected account API to pre-fill account information.

Create a hosted flow instance

Create a hosted flow instance for the connected account. Specify the account_id and the hosted flow template id provided by Airwallex. Also specify a return_url to redirect the account holder after the flow is complete.

A successful request returns a hosted flow URL (url) and a hosted flow instance ID (id). Do not share the URL with the account holder until you have authorized it in Authorize the user into the hosted flow.

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 or account; account status is SUSPENDED, that is, disabled or failed onboarding verification)
• 500 (server error)

Example request

1curl -X POST https://api-demo.airwallex.com/api/v1/hosted_flows/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "account_id": "acct_wst1AJZWbOx2Ijf-PDS123w",
6    "error_url": "{{PLATFORM_ERROR_URL}}",
7    "metadata": {},
8    "return_url": "{{PLATFORM_RETURN_URL}}",
9    "template": "{{TEMPLATE_OPEN_ID}}"
10  }'

Example response

1{
2  "id": "ahfi_Y9_AbPkQQQe0K81XcHLy5w",
3  "metadata": {
4  },
5  "result": {
6  },
7  "status": "string",
8  "url": "https://airwallex.com/app1/hostedflow?ahfi_id=<hosted_flow_instance_id>&return_url=<return_url>"
9}

Authorize the user into the hosted flow

Call Authorize the flow API using the hosted flow instance id (returned in the previous step) to authorize the URL. The authorized URL is short-lived—redirect the account holder as quickly as possible after receiving it.

The account holder can respond to any open RFIs displayed on the page.

Error responses could include:

• 400 (hosted flow already finished)
• 403 (not authorized for this action, account, or flow)
• 404 (hosted flow instance ID not found)
• 500 (server error)

Example request

The identity field is your platform's identifier for the user, such as a user ID, session ID, or access token.

1curl -X POST https://api-demo.airwallex.com/api/v1/hosted_flows/{{HOSTED_FLOW_INSTANCE_ID}}/authorize \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "identity": "{{ANY_USER_IDENTIFIER}}"
6  }'

Example response

1{
2  "authorization_code": "<authorization_code>",
3  "id": "<hosted_flow_instance_id>",
4  "metadata": {
5  },
6  "result": {
7  },
8  "status": "string",
9  "url": "https://airwallex.com/app1/hostedflow?ahfi_id=<hosted_flow_instance_id>&authorization_code=<authorization code>&return_url=<return url>&error_url=<error url>"
10}

Handle session timeout

Session timeouts may occur due to inactivity or if the account holder exits the hosted flow without completing the form. If the session expires, Airwallex shows a session prompt that lasts 60 seconds before logging the user out with error code TOKEN_EXPIRED.

The account holder may return to the form to complete the information after a session expiry. To handle this scenario:

1. Check whether a saved hosted flow instance ID for the account exists (from Create a hosted flow instance).
2. Re-authorize the account holder by calling Authorize the flow API to retrieve a link with a new authorization code (see Authorize the user into the hosted flow).
3. Redirect the account holder to the new URL from the response.

Handle the response

Listen for account status changes via account webhooks.

Error handling

Next steps

Now that your hosted flow integration is set up, you can:

• Subscribe to account status webhooks to receive real-time notifications when onboarding completes or an RFI is raised.
• Handle onboarding RFIs if Airwallex requests additional information from the account holder.