Hosted Onboarding

Hosted KYB is the recommended solution for platforms to activate payment methods for customers without having to build your own full-fledged payment activation form around Airwallex APIs.

Our hosted form dynamically takes care of collecting required information to activate payment methods, customized by business scenario and payment methods. You’ll directly leverage our UX optimizations for error handling. You can also customize the visual appearance of the onboarding form to reflect your brand.

Through Hosted Payment Method Activation, a platform can

• Via an API, retrieve a Hosted flow link unique to a connected account
• Direct the end user who clicks on the link into an Airwallex-hosted environment to complete a white-labeled payment activation form
• After the payment activation form is complete, the end user is automatically redirected back into your environment (or to any return URL of choice)

Before you begin

• Contact your Airwallex Account Manager to:
  • Enable connected account hosted 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.

Step 1: Create an account and pre-fill information

POST /api/v1/accounts/create

Handle response and error logic. Make sure to save the account_id for this account from the response.

JSON
1
2{
3  "account_details": {...}
4  "account_usage": {...}
5  "customer_agreements": {...},
6  "primary_contact": {...}
7  "metadata": {...}
8}
9
10Use the Update Account API to update / add more information. 
11
12POST /api/v1/accounts/{id}/update 
13

Step 2: Create hosted flow

POST /api/v1/hosted_flows/create

Create a hosted flow instance for an account. Specify the account_id of the connected account for which you are creating the flow (from Step 2), and the hosted flow template id (from Step 1).

Request

JSON
1{ 
2  "account_id": "<account id>",
3  "template": "<template open id>"
4  "return_url": "<platform return url>",
5  "error_url": "<platform error url>", 
6  "metadata": {
7    "<anything>": "<anything>", ...
8  }
9}
10

Response

JSON
1{
2  "id": "<hosted flow instance id>",
3  "url": "https://airwallex.com/app1/hostedflow?
4     ahfi_id=<hosted flow instance id>
5     &return_url=<return url>",
6  "result": {},
7  "metadata": {
8    "<anything>": "<anything>", ...
9  }
10}
11

From the response, make sure to save the hosted flow 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 – that is, disabled or failed KYC)
• 500 (server error)

Step 3: Authorize the user into the hosted flow

POST /api/v1/hosted_flows/{id}/authorize

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

Request

JSON
1{
2  "identity": "<any user identifier>"  // platform’s identifier for the user, such as a user ID, session ID, or access token.
3}
4

Response

JSON
1{
2  "id": "<hosted flow instance id>",
3  "authorization_code": "<authorization code>",
4  "url":
5    "https://airwallex.com/app1/hostedflow?
6     ahfi_id=<hosted flow instance id>
7     &authorization_code=<authorization code>     
8     &return_url=<return url>
9     &error_url=<error url>",
10  "result": {},
11  "metadata": {
12    "<anything>": "<anything>", ...
13  }
14}
15

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)

Step 4: Handle re-entry

The user may exit the hosted onboarding form without finishing and attempt to re-enter later. If the user has not exited but the session expired, we will show a session prompt that lasts for 60 seconds before we logout the user with error code TOKEN_EXPIRED.

In order to handle re-entry,

• Check if a saved hosted flow instance id for the account exists (from Step 3).
• If the account has a saved hosted flow, re-authorize the user: Call the POST /api/v1/hosted_flows/{id}/authorize endpoint to retrieve a link with a new authorization code
• Redirect the user to the new url from the response.

Error handling