Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Scale
Overview
Why use Scale?Case study - Marketplace platformCase study - Invoicing / supply chain financing platform
Get started
Step 1: Register your platformStep 2a: Create and connect a connected account for businessesStep 2b: Create and connect a connected account for individuals
Step 3: Transact on behalf of the connected account

Step 2b: Create and connect a connected account for individuals

Using the Scale API you can create Airwallex accounts for the users of your platform or marketplace. Below explains how you can onboard your users if they are individuals without a registered company entity.

There are three main steps to successfully onboard the individuals to Airwallex:

  1. Determining and collecting the information/ data required
  2. Creating the account
  3. Submitting the account for activation

Additionally you need to consider cases where the activation requires additional measures:

  1. Handling additional requirements during account activation

1. Determining and collecting the information/ data required

To determine the the information you need to collect from your users, please check the API documentation with the dynamic schema: https://www.airwallex.com/docs/api#/Scale/Accounts/_api_v1_accounts_create/post API

All required fields have to be filled before activating the account. Filling in optional fields before activating the account will increase the success rate of account activation. You may collect the required fields from users using your user interface, or use information previously collected or determined from your own data (e.g., monthly transaction volumes).

2. Creating the account

You can create accounts for your users with the accounts API. The accounts created will be automatically linked to your platform account and you will have authorization to transact on behalf of the connected accounts using Airwallex's Scale APIs.

There are two ways to create accounts with the Scale API endpoints:

  1. Create an account with all required information at once
  2. Create an empty account and update required information step-by-step

2.1 Create an account with all required information at once

Creating an account with all required information at once is useful if you are storing a copy of the information on your servers or if the users fill in the information all at once. With this, you’ll limit the number of API calls you have to make to get going.

If you have collected any image or document from the user in step 1 (e.g., a copy of their identity document), then you’ll first need to upload the document to the Airwallex server using the file service API <POST /api/v1/files/upload>.The response of the file service API endpoint will include a file_id, which you should save so that you can reference it in the next step. Once all images/ documents have been successfully uploaded, you can proceed.

Shell

Next, you can create an account via <POST /api/v1/accounts/create>. You can include in the request body all required information collected in step 1. For any images/ documents (e.g., copy of identity document), you need to include the file_id that you saved. In the response of the create account endpoint, you’ll receive an account ID, with which you can access the account later on.

Shell

2.2 Create an empty account and update required information step-by-step

Creating an empty account and updating the required information step-by-step is useful if you do not store a copy of the information on your server and you’ll want to enable the user to provide information in stages.

You can start out with creating an empty account via <POST /api/v1/accounts/create>, for which you only need to provide three pieces of information:

  • Primary contact of the user (either email or mobile phone number)
  • Agreement to data sharing
  • Agreement to terms and conditions

You’ll receive an account ID, with which you can access the account later on.

Shell

An example response:

Shell

Afterwards you can add any information collected from the user with the update account endpoint <POST /api/v1/accounts/{account_id}/upload>. You can replace {account_id} with the account id received when creating the empty account, to identify the account to which you want to add or change information.

If you are collecting any image or document from the user (e.g., a copy of their identity document), then you’ll need to upload the document to the Airwallex server using the file service API <POST /api/v1/files/upload>.The response of the file service API endpoint will include a file_id. This file_id can then be used to add the image/ document to the account with the update account endpoint.

You can call the update account endpoint as many times as you wish until all the information required has been added. You can also use the update account endpoint to overwrite information previously added.

Shell
Shell

3. Submit the account for activation

Once all the required information has been collected, you can submit the account for activation using <POST /api/v1/accounts/{account_id}/submit>. If the information provided fulfills the requirements determined in step 1, the account status will be updated to SUBMITTED.

Shell

You can subscribe to account update webhooks to be notified once the activation has been completed. For individuals, most accounts will be activated within a minute. However, if further review is required, the activation may take 24 hours or longer. Alternatively, you can query the status of the account using <GET /api/v1/accounts/{account_id}> and look at the <status> field at any time.

Shell

If the information you have provided is not sufficient based on the requirements determined in the first step, the call <POST /api/v1/accounts/{account_id}/submit> will respond with the error code below: 400 Possible errors: field_required, invalid_argument

Example response:

Shell

4. Handling additional requirements during account activation

Sometimes more steps are required to successfully complete the account activation, even if the information you submitted in step 2 was initially deemed sufficient. There are generally two reasons this might happen:

  • Failed identity verification: During KYC we have to verify the identity of the individual. If we are unable to verify the identity, you’ll need to ask the individual to submit a second form of identification, or retry after correcting any errors in the previously submitted data.
  • Additional information requests: During KYC, we have to assess the risk of each individual, in order to decide whether the account can be activated or not. In some instances, more information will be required to make that decision.

Currently additional information requests will be handled manually via email. We’ll reach out to you if more information on an individual is required. Later on you’ll be able to subscribe to a webhook to be informed of additional information requests, and will be able to submit the information directly through the API endpoints.