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 APIAPI to set up a linked bank account and add funds via direct debits.

Before you begin

• Obtain your access tokenAPI 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 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 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, or approving an authorization from your external banking application. Currently, this is available for Linked Accounts in Australia, Canada, Europe (SEPA region), the United States, the United Kingdom and Singapore.
• Micro-deposits: Verify by entering the 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. Using PLAID and TRUELAYER also enables you to Check available balancesAPI 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.

Please note that Open Banking in Australia via PayTo works differently from other regions. See Australia (AU_PAYTO_DEBIT) for more details on how to create a Linked Account via PayTo in Australia.

For Singapore eGIRO and Australia PayTo, only Linked Accounts verified using Open Banking can add funds via direct debit, as the Linked Bank Account owner must provide authorization through their banking app. If you are creating a linked account to add funds via direct debit in the aforementioned countries, please keep this in mind.

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 contact or contract with our Open Banking partners separately.

Call Generate a Linked Account authenticationAPI 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.

Plaid verification

If the type is PLAID:

• country_code: The country the external bank account is located.
• 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.

Example request

1curl -X POST https://api.sandbox.airwallex.com/api/v1/linked_accounts/auth \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "plaid": {
6      "client_name": "Airwallex",
7      "redirect_url": "https://www.airwallex.com"
8    },
9    "type": "PLAID"
10  }'

Example response

1{
2  "plaid": {
3    "expires_at": "2022-06-29T11:25:39+0000",
4    "link_token": "link-sandbox-463f3464-287c-4a75-adf2-85bc07c2dd89"
5  },
6  "type": "PLAID"
7}

TrueLayer verification

If the type is TRUELAYER:

• country_code: The country the external bank account is located.
• provider_id: Unique ID of the external financial institution as provided by Truelayer. See the Truelayer providers API for a list of supported institutions.
• redirect_url: URL that the user will be redirected to at the end of the TrueLayer modal. Please also provide this URL to your Account Manager.

Example request

1curl -X POST https://api.sandbox.airwallex.com/api/v1/linked_accounts/auth \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "truelayer": {
6      "country_code": "GB",
7      "provider_id": "ob-monzo",
8      "redirect_url": "https://www.airwallex.com"
9    },
10    "type": "TRUELAYER"
11  }'

Example response

1{
2  "truelayer": {
3    "auth_url": "https://auth.truelayer-sandbox.com?client_id=sandbox-airwallex-5c4af6&redirect_uri=https://www.airwallex.com&provider_id=ob-monzo&state=6781472155828238&response_type=code&scope=info%20accounts%20balance%20offline_access"
4  },
5  "type": "TRUELAYER"
6}

eGIRO verification

If the type is EGIRO:

• swift_code: 11-digit SWIFT code of the external bank account.
  • An UNAVAILABLE_BANK_CODE error will be returned when the specified bank does not support eGIRO. For such cases, you may create a linked account without direct debit enabled using micro-deposit verification instead. See the list of eGIRO participating banks for supported financial institutions.
• entity_type: BUSINESS or INDIVIDUAL.
• redirect_url: URL that the user will be redirected to at the end of the eGIRO modal.
• reference: Unique mandate ID specified in the request, which will appear on the authorization request to the payer on their banking app. Only accept alphanumeric characters in all caps without spacing, up to 35 characters long.

EGIRO itself functions as a direct debit scheme; hence, to create a Linked Account via eGIRO, you must collect mandate authorization from your customers and submit that information in Create a Linked AccountAPI. If you do not intend to use the Linked Account for adding funds via Direct Debit, then it's recommended to Create the Linked Account via micro-deposit verification instead.

Example request

1curl -X POST https://api.sandbox.airwallex.com/api/v1/linked_accounts/auth \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "egiro": {
6      "swift_code": "HSBCSGS2XXX",
7      "entity_type": "INDIVIDUAL",
8      "reference": "AWXTESTTBJRP3VRQ",
9      "redirect_url": "https://www.airwallex.com"
10    },
11    "type": "EGIRO"
12  }'

Example response

1{
2    "egiro": {
3        "auth_url": "https://egiro.dbs.com/api/v1/edda/authorize/creation?applicantBankCode=HSBCSGS2XXX&boDDARefNo=AWXTESTTBJRP3VRQ&boName=Airwallex%20Singapore%20Pte.%20Ltd.&boTransactionRefNo=BOAIR6561Z01AIR20250820090936832669&clientID=BOAIR6561Z01AIR&purpose=OTHR&requestID=e94728e6-6264-4363-b3ee-40555c9512ae&requestType=Creation&segment=Retail&nonce=95888807390712515308&timestamp=1755680976645&signature=-----BEGIN%20PGP%20SIGNATURE-----%0AVersion%3A%20BCPG%20v1.67%0A%0AiQEcBAABCAAGBQJopZDQAAoJENJgPC2%2F3GxTdFQIAIxevyHLG7OtU2tocm1fVE6P%0Asxo2HGW5P3CaOTJ9TF%2FhmdnMXlCPTLKhDEGbjAeiC0nG5NNLzrPCxd7cll4pe64b%0AaHf2dYOQHEt6OVlhk5VppjTkz7CSzLhoDygDKIVlHV0v5yjWttTVHuJbbnjwRWV3%0A5XaYOM%2Fd8gQRKmQJPi6osmLifRTPZVK%2F%2FtvpFkXBnBM5uB%2BA%2Bc%2FJ7Th6uwxdjw0O%0AxmIg5zOFaziXM41LC1T8X%2B6jSKLKucLWa%2FFRhanx%2BwEVlpfc7aY3erxNMMa9Wrdw%0AcG%2F71DJvUO8shylrH%2FjpFhqKGRGPa7XpJaiIjyQC%2BNAqVfnXg%2Fff62nUGlHhaaM%3D%0A%3DySJX%0A-----END%20PGP%20SIGNATURE-----%0A"
4    },
5    "type": "EGIRO"
6}

Create a Linked Account

Call Create a Linked AccountAPI 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 mandateAPI.

You can subscribe to Linked Account webhook events to receive any Linked Account status transitions. See Linked Account statuses for more information.

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.

Create Linked Account via Plaid

For PLAID as the preferred_verification_type, you should provide the following details parsed from the Plaid Modal’s onSuccess callback:

• public_token: The Plaid public token
• institution:
  • id: Plaid’s unique identifier of the external bank account’s financial institution
  • name: Name of the external bank account’s financial institution
• account: