Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Treasury
Overview
Introduction to TreasurySupported regions and currencies
Linked Accounts
Get started with Linked AccountsAdd funds via direct debits from Linked AccountsManage Linked Accounts

Get started with 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.
  • As a Scale platform account, 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 the x-on-behalf-of header of your API request. To learn about how you can register as a platform and set up this solution, see our step-by-step guide on Scale integration.

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 in the United States).
  • 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

Please contact your Account Manager to enable the appropriate Open Banking partner for your region, and receive instructions to set up an Open Banking modal on your own front-end experience.

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.
  • client_name: The name of your business to be displayed in the modal.
  • redirect_url: URL to handle the Oauth verification flow.

Example request

Shell

Example response

JSON

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.

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_type and currency.
  • 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

Shell

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.

Listed below are the possible statuses after you verify the Linked Account.

StatusDescription
PROCESSINGLinked account activation is in progress. The customer should wait for the status to update.
SUCCEEDEDLinked account has been created successfully.
FAILEDThe request to create a Linked Account was unsuccessful.

Example response

JSON

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 response

JSON

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.

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.

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

Shell

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.

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 the next_action object, 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 to FAILED.
    • 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.

Review status codes to track status transitions when Linked Accounts are created and verified.

Example request

Shell

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.

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.

Example request

Shell

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

JSON

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

Shell

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

JSON
On this page