Linked Accounts
A Linked Account is a verified external financial account (such as a bank account, credit/debit card, or e-wallet account) that is bound to an Airwallex account. Currently, we only support linking bank accounts owned by the business that signed up for the Airwallex account, or one of its Ultimate Beneficial Owners (UBOs). Learn how to use Airwallex API API to set up a linked bank account and add funds via direct debits.
Before you begin
- 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.
- Contact your Airwallex Account Manager to enable Linked Account APIs on your Airwallex account.
- Set up webhooks to receive notifications on Deposit events (currently only available for direct debit deposits).
- As a platform, you can call all Linked Accounts API endpoints on behalf of your connected accounts by specifying the connected account's open ID (in the format
acct_xxxxxxxx) in thex-on-behalf-ofheader of your API request. To learn about how you can register as a platform and set up this solution, see Global Treasury and Banking as a Service solutions.
To successfully link an external bank account, Airwallex must first verify its ownership. Airwallex offers two options to verify the external bank account:
- Open Banking: Verify by securely entering your credentials in an Open Banking modal. Currently, this is available for Linked Accounts in the United States, the United Kingdom, and Europe (SEPA region).
- Micro-deposits: Verify by entering micro-deposit amounts sent to your external bank account.
We recommend Open Banking, as it allows you to complete the process in just a few minutes, and enables you to Check Linked Account balance before creating direct debit deposits. However, if your external bank account is in a region or with a bank not supported by Open Banking, please proceed to use micro-deposits.
Create a Linked Account using Open Banking verification
Get an Open Banking authentication token
Airwallex works with external partners to offer Open Banking for account verifications. Please contact your Account Manager to receive instructions to set up an Open Banking modal on your own front-end experience. The integration uses Airwallex API endpoints, and you do not need to separately contact or contract with our Open Banking partners.
Call Generate a Linked Account authentication API to retrieve a Link Token required to access the Open Banking modal.
Provide the following parameters in your request:
type: Specify a verification type for your external bank account.
If the type is PLAID:
country_code: The country the external bank account is located in.client_name: The name of your business to be displayed in the modal.redirect_url: URL that the user will be redirected to at the end of the Plaid modal. Please also provide this URL to your Account Manager.
If the type is TRUELAYER:
country_code: The country the external bank account is located in.provider_id: Unique ID of the financial institution as provided by Truelayer here.redirect_url: URL that the user will be redirected to at the end of the TrueLayer modal.
Example request
Example response
Create a Linked Account
Call Create a Linked Account API specifying the external bank account location under Linked Account type (e.g. US_BANK) and corresponding bank account information, including information obtained from your Open Banking modal.
Before you can add funds via direct debit from a Linked Account, you must obtain authorization from the external bank account owner in the form of a signed mandate (or signed agreement). You may submit mandate information while creating a Linked Account, or later by calling Update a direct debit mandate API.
You can subscribe to Linked Account webhook events to receive any Linked Account status transitions. See Linked Account statuses for more information.
To create and sign direct debit mandates via API, as a first step, please contact your Airwallex Account Manager to walk you through the direct debit mandate requirements and to enable this capability on your account.
Provide the following parameters in your request:
type: Type of Linked Account.- Details about the specific Linked Account. When using Open Banking, you only need to provide
entity_typeandcurrency. preferred_verification_type: Type of verification used to link your external account.- Open Banking details about the specific Linked Account, such as token information to grant Airwallex access to account details.
- Mandate details, if you plan to use direct debit later.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Listed below are the possible statuses after you verify the Linked Account.
| Status | Description |
|---|---|
| PROCESSING | Linked account activation is in progress. The customer should wait for the status to update. |
| SUCCEEDED | Linked account has been created successfully. |
| FAILED | The request to create a Linked Account was unsuccessful. |
Example response
Refresh an expired Linked Account
Linked Accounts verified by Open Banking could expire if the external bank account owner changes their login credentials, revokes our access to their account, or naturally after a long period of time (typically above one year).
If the status of your Linked account returns as REQUIRES_ACTION, call Refresh a Linked Account authentication API to acquire a new Link Token for your Open Banking modal.
Example request
Example response
Once the Linked Account owner has completed the Open Banking modal, call Complete the Authentication Refresh API to reactivate your Linked Account. You do not need another Public Token for this request.
Confirm a Linked Account
During the Open Banking experience with TrueLayer, the user is permitted to select more than one financial account under the same bank credentials. If this happens, you will need to identify a single account to link with Airwallex.
When calling Create a Linked Account API or Get a Linked Account by ID API, you will see the Linked Account status as REQUIRES_ACTION, with confirm_account returned under the next_action object. Under candidate_accounts, you will see a list of all financial accounts that have been successfully verified, and can be converted into a Linked Account.
To select the Linked Account you would like to create, call Confirm a Linked Account among candidate accounts API and input the corresponding account_identity.
Example request
Create a Linked Account using micro-deposit verification
Create a Linked Account
Call Create a Linked Account API specifying the external bank account location in Linked Account type (e.g. AU_BANK, US_BANK) and corresponding bank account information. Set MICRO_DEPOSIT as your preferred_verification_type.
Before you can add funds via direct debit from a Linked Account, you must obtain authorization from the external bank account owner in the form of a signed mandate (or signed agreement). You may submit mandate information while creating a Linked Account, or later by calling Update a direct debit mandate API.
You can subscribe to Linked Account webhook events to receive any Linked Account status transitions. See Linked Account statuses for more information.
To create and sign direct debit mandates via API, as a first step, please contact your Airwallex Account Manager to walk you through the direct debit mandate requirements and to enable this capability on your account.
Provide the following parameters in your request:
type: Type of Linked Account.- Details about the specific Linked Account.
preferred_verification_type: Type of verification used to link your external account.- Mandate details, if you plan to use direct debit later.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Example response
Verify by entering micro-deposit amounts
After submitting a Create a Linked Account API request, you should receive REQUIRES_ACTION in the status parameter within the response.
REQUIRES_ACTION: Indicates that customer action such as verifying the Linked Account with micro-deposits is pending. Inspect the parameters in thenext_actionobject, which provides details of the next action to be taken to activate the Linked Account.micro_deposit_count: Number of micro-deposits sent to the linked bank account.remaining_attempts: Remaining attempts left to enter the correct micro-deposit amount. When this becomes 0, the status field will be updated toFAILED.type: Type of action to be taken, e.g,verify_micro_deposits.
Call Verify a Linked Account with micro-deposits API using your Linked Account ID in the URL. Specify the two micro-deposits in the amounts[] request parameter, in any order.
When the verification of the Linked Account is complete, Airwallex returns the status as SUCCEEDED. If you submitted a direct debit mandate with type GB_BACS_DEBIT, please also wait 3-4 days for the mandate to be activated, during which your Linked Account status will remain as PROCESSING.
Review status codes to track status transitions when Linked Accounts are created and verified.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Example response
Retrieve details of your Linked Account
To retrieve details for a specific Linked Account, call Get a Linked Acount by ID API by specifying Linked Account ID in the endpoint URL.
You can subscribe to Linked Account webhook events to receive any Linked Account status transitions. See Linked Account statuses for more information.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Example response
You can also retrieve all Linked Accounts associated with your Airwallex account using Get a list of Linked Accounts API. If you want to filter the results, provide additional parameters for time period (from_created_at, to_created_at), pagination (page_size, page_num), status, and/or country_code of the account.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.