Multi-entity hosted flow

The multi-entity hosted flow lets platform partners onboard several connected account entities in a single Airwallex-hosted flow. Instead of collecting identity information for each entity separately, account holders provide the required details for all of their entities in one pass. This streamlines onboarding and minimizes the additional information you need to collect when you add new entities. Onboarding verification, previously referred to as Know Your Customer (KYC), is the process by which Airwallex verifies the identity of a connected account holder.

At a high level, the multi-entity hosted flow works as follows:

• Retrieve a secure, short-lived hosted flow link that covers all of the platform partner's entities via the Airwallex API.
• Redirect the account holder who clicks the link to an Airwallex-hosted environment to complete a white-labeled additional information form.
• After the form is complete, Airwallex automatically redirects the account holder back to your environment, or to any return URL you specify when creating the hosted flow instance.

To preview the end user experience, see the sandbox environment. This method supports business accounts only.

Before you begin

Ensure you have the following before you start:

• Multi-entity 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 or Technical Account Manager to request access and any customization of your landing page (business name, logo, and color). The customized logo appears on all hosted flow pages.
• An access tokenAPI for your Airwallex account.
• A native API integration for all other funds flow and payments control.

Create an account for each entity

Create a connected account for each entity you want to onboard. Call Create a connected accountAPI once per entity and provide the required fields in each request. Each connected account must agree to the terms of data usage before the API request is made.

Save the account_id returned in each response—you need all of them when you create the hosted flow instance in the next step. Implement error handling for each request.

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

Example request

1curl -X POST https://api.sandbox.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        "registration_address": {
12          "country_code": "AU"
13        }
14      }
15    },
16    "customer_agreements": {
17      "agreed_to_terms_and_conditions": true,
18      "agreed_to_data_usage": true
19    }
20  }'

Create a hosted flow instance

Create a single hosted flow instance that covers all of the accounts created in Create an account for each entity. Set the fields in the request body as follows:

• account_id: Any one of the account IDs created for the entities. This value must be one of the IDs listed in flow_data.kyc_multi_entity.accounts.
• template: The hosted flow template open ID provided by your Airwallex Account Manager.
• flow_data.kyc_multi_entity.accounts: The list of all account IDs related to this flow.
• return_url: The URL to redirect the account holder to after the flow is complete.
• error_url and metadata: Optional. See Create a hosted flowAPI for details.

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, or request data invalid)
• 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.sandbox.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_3-OGqTUaMX6yPM6sxVQw1Q",
6    "error_url": "{{PLATFORM_ERROR_URL}}",
7    "metadata": {},
8    "return_url": "{{PLATFORM_RETURN_URL}}",
9    "template": "{{TEMPLATE_OPEN_ID}}",
10    "flow_data": {
11      "kyc_multi_entity": {
12        "accounts": [
13          "acct_3-OGqTUaMX6yPM6sxVQw1Q",
14          "acct_61wLKVReOK2Yb7f583FHYw"
15        ]
16      }
17    }
18  }'

Example response

1{
2  "id": "ahfi_Y9_AbPkQQQe0K81XcHLy5w",
3  "url": "https://airwallex.com/app1/hostedflow?ahfi_id=<hosted_flow_instance_id>&return_url=<return_url>",
4  "result": {},
5  "metadata": {},
6  "status": "INIT",
7  "flow_data": {
8    "kyc_multi_entity": {
9      "accounts": [
10        "acct_3-OGqTUaMX6yPM6sxVQw1Q",
11        "acct_61wLKVReOK2Yb7f583FHYw"
12      ]
13    }
14  }
15}

From the response, save the hosted flow id for use in the following steps.

For the full API reference, see Create a hosted flowAPI.

Authorize the user into the hosted flow

Call Authorize the flowAPI 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 completes a single additional information form covering all entities and 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.sandbox.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  "result": {},
6  "status": "string",
7  "url": "https://airwallex.com/app1/hostedflow?ahfi_id=<hosted_flow_instance_id>&authorization_code=<authorization_code>&return_url=<return_url>&error_url=<error_url>"
8}

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 flowAPI 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. Airwallex verifies each entity in the flow, so you receive status updates for each connected account.

Error handling

Next steps

Now that your multi-entity 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 for any entity.
• Handle onboarding RFIs if Airwallex requests additional information from an account holder.