Native API
Learn how to create and activate connected accounts using Native API, including handling KYC requirements using this step-by-step tutorial.
Step 1: Create connected accounts
Connected accounts that you create via Accounts API will be linked to your Platform and you will have authorization to transact on behalf of the connected account using Airwallex's Scale APIs.
By confirming agreement to Airwallex's terms and conditions, you consent to the terms covering the relationship between Airwallex, your business and the counterparty on whose behalf you are opening the account, and in doing so, Airwallex is authorised to take action on the connected account according to your instructions.
The response includes the Airwallex account ID for the connected account, which you will use in the next steps.
Step 2: Update and submit account for KYC
Determine data required for KYC (for API submission only)
To determine the information you need to collect from your users, please review the KYC requirements for business and individual .
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).
Attach data & documents for KYC
Documents may be uploaded to the Airwallex server using the File service API. 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 documents have been successfully uploaded, you can proceed.
Accounts may be created & updated in stages using Accounts API.
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 aim to have the user provide information to your Platform in stages.
You can start out with creating an empty account via Accounts API, 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
An example response:
Afterwards you can add any information collected from the user with the update Accounts API. 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.
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.
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.
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
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:
Step 3: Handle additional requests for Information (RFI)
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.
Read this document to find out more about our RFI options to handle additional information requests for KYC.