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 currencies and payments
Treasury Resources
Global AccountsLinked Accounts
Getting Started

Linked Accounts

This guide describes how to use Airwallex APIs to link a bank account to your Airwallex account. Linked accounts are external accounts that you can use to fund your Airwallex Wallet via direct debit, withdrawals, or to meet any compliance requirements.

Before you begin

Step 1: Submit a request to create a Linked Account

Call Create a Linked Account API with the bank information and the Linked Account type, which identifies the location of the external bank account, for example, AU_BANK, US_BANK.

You can also submit the signed mandate for authorizing direct debits. For information on direct debits, see Direct Debits from Linked Accounts.

Example request

curl --request POST \
--url 'https://api-demo.airwallex.com/api/v1/linked_accounts/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data '{ \
  "au_bank": { \
    "account_name": "Tester Smith", \
    "account_number": "89098199202", \
    "bsb": "063001", \
    "currency": "AUD", \
    "entity_type": "BUSINESS" \
  }, \
  "mandate": { \
    "email": "tester@test.com", \
    "signatory": "Tester Smith", \
    "type": "AU_BECS_DEBIT", \
    "version": "1.1" \
  }, \
  "preferred_verification_type": "MICRO_DEPOSIT", \
  "type": "AU_BANK", \
}'

Example response

{
  "au_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "bsb": "063001",
    "currency": "AUD",
    "entity_type": "BUSINESS"
  },
  "id": "114907b3-a708-483e-b97a-be3742905f6f",
  "next_action": {
    "micro_deposit_count": 2,
    "remaining_attempts": 3,
    "type": "verify_micro_deposits"
  },
  "reason": "lack of information",
  "status": "REQUIRES_ACTION",
  "supported_currencies": [
    "AUD"
  ],
  "type": "AU_BANK",
}

Step 2: Verify your Linked Account

After submitting Create a Linked Account API request, you should receive REQUIRES_ACTION in the status parameter.

  • 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, i.e, verify_micro_deposits.

To successfully link an external bank account, Airwallex must first verify the ownership of the external bank account. This bank account must be owned by the business or by one of the individuals associated with the business as provided to Airwallex during onboarding. By triggering a micro-deposit verification, Airwallex will send two very small payments to the external bank account. The owner must provide the exact amounts of these payments, to verify their ownership of the account.

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.

Listed below are the possible statuses after you verify the Linked Account with micro-deposits.

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.
SUSPENDEDLinked account has been suspended by Airwallex.

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

Example request

curl --request POST \
--url 'https://api-demo.airwallex.com/api/v1/linked_accounts/<your_linked_account_id>/verify/micro_deposits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data '{ \
  "amounts": [ \
    0.08, \
    0.09 \
  ] \
}'

Example response

{
  "au_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "bsb": "063001",
    "currency": "AUD",
    "entity_type": "BUSINESS"
  },
  "id": "114907b3-a708-483e-b97a-be3742905f6f",
  "next_action": {
    "micro_deposit_count": 2,
    "remaining_attempts": 3,
    "type": "verify_micro_deposits"
  },
  "reason": "lack of information",
  "status": "SUCCEEDED",
  "supported_currencies": [
    "AUD"
  ],
  "type": "AU_BANK",
}

Retrieve details of your Linked Account

Call Get a Linked Acount by ID API by specifying Linked Account ID in the endpoint URL.

Example request

curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/linked_accounts/<your_linked_account_ID>' \
--header 'Authorization: Bearer <your_bearer_token>'

Example response

{
  "au_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "bsb": "063001",
    "currency": "AUD",
    "entity_type": "BUSINESS"
  },
  "eu_bank": {
    "account_name": "Tester Smith",
    "currency": "AUD",
    "entity_type": "BUSINESS",
    "iban": "DE372022080000903344401",
    "swift_code": "DBSSSGSG"
  },
  "gb_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "currency": "AUD",
    "entity_type": "BUSINESS",
    "sort_code": "608382"
  },
  "hk_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "bank_code": "003",
    "currency": "AUD",
    "entity_type": "BUSINESS"
  },
  "id": "114907b3-a708-483e-b97a-be3742905f6f",
  "next_action": {
    "micro_deposit_count": 2,
    "remaining_attempts": 3,
    "type": "verify_micro_deposits"
  },
  "reason": "lack of information",
  "sg_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "currency": "AUD",
    "entity_type": "BUSINESS",
    "swift_code": "DBSSSGSG"
  },
  "status": "SUCCEEDED",
  "supported_currencies": [
    "AUD"
  ],
  "type": "AU_BANK",
  "us_bank": {
    "account_name": "Tester Smith",
    "account_number": "89098199202",
    "ach": "084106768",
    "currency": "AUD",
    "entity_type": "BUSINESS"
  }
}

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

curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/linked_accounts?country_code=US&from_created_at=string&page_num=0&page_size=100&status=string&to_created_at=string' \
--header 'Authorization: Bearer <your_bearer_token>'

Example response

{
  "has_more": false,
  "items": [
    {
      "au_bank": {
        "account_name": "Tester Smith",
        "account_number": "89098199202",
        "bsb": "063001",
        "currency": "AUD",
        "entity_type": "BUSINESS"
      },
      "eu_bank": {
        "account_name": "Tester Smith",
        "currency": "AUD",
        "entity_type": "BUSINESS",
        "iban": "DE372022080000903344401",
        "swift_code": "DBSSSGSG"
      },
      "gb_bank": {
        "account_name": "Tester Smith",
        "account_number": "89098199202",
        "currency": "AUD",
        "entity_type": "BUSINESS",
        "sort_code": "608382"
      },
      "hk_bank": {
        "account_name": "Tester Smith",
        "account_number": "89098199202",
        "bank_code": "003",
        "currency": "AUD",
        "entity_type": "BUSINESS"
      },
      "id": "114907b3-a708-483e-b97a-be3742905f6f",
      "next_action": {
        "micro_deposit_count": 2,
        "remaining_attempts": 3,
        "type": "verify_micro_deposits"
      },
      "reason": "lack of information",
      "sg_bank": {
        "account_name": "Tester Smith",
        "account_number": "89098199202",
        "currency": "AUD",
        "entity_type": "BUSINESS",
        "swift_code": "DBSSSGSG"
      },
      "status": "SUCCEEDED",
      "supported_currencies": [
        "AUD"
      ],
      "type": "AU_BANK",
      "us_bank": {
        "account_name": "Tester Smith",
        "account_number": "89098199202",
        "ach": "084106768",
        "currency": "AUD",
        "entity_type": "BUSINESS"
      }
    }
  ]
}
On this page