Search...
APIJSLog inGet started
Airwallex logo
Home
Platform APIs
Connected Accounts
Accounts
Payments
Transactional FX
Payouts
Issuing
Embedded Finance Use Cases
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Business Account Help Center
API Reference
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Transfers
Create a transfer
Validate a transferManage transfers
Transfers to countries/regions with capital controls
Transfers via Airwallex Pay
Embedded Transfer component
Batch transfers
Beneficiaries
Payers
Tax filing
Errors
Test and go live
Older API versions

Transfers via Airwallex Pay

New feature: This page introduces the new wallet transfer experience with Transfer API endpoints API for API version 2025-04-25 or later. For older API versions, please see Wallet transfers (Legacy).

You can send funds directly to businesses who also own Airwallex accounts by creating a transfer to an Airwallex account. Learn how to do this programmatically with our Access own account info API and Transfer API endpoints API endpoints in the following sections.

The current transfer approval workflow also applies to transfers via Airwallex Pay.

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.

Step 1: Prepare required beneficiary information

Before creating a transfer to an Airwallex account, you will need to obtain your beneficiary’s Airwallex account number and account name. This is similar to obtaining a beneficiary’s bank account number and account name when making a bank transfer to their bank account.

There are two ways you can do this:

  • Use OAuth to allow your beneficiary to grant your application permission to access its Airwallex account number and account name via Access own account info API.

  • Ask your beneficiary to provide you with its Airwallex account number and account name (currently they can only access them via Access own account info API).

In this section, we will elaborate on using OAuth to obtain your beneficiary’s Airwallex account info.

Set up your application

To do this, you will need to:

  • Register an application with us, and obtain an app ID and client secret

  • Define the scope for your application

    • In this case, the required scope for accessing your beneficiary’s Airwallex account number and account name is r:awx_action:account.wallet_info_view

  • Provide a redirect URI that your application takes beneficiaries to after granting authorization

For more information, read this Get started page for partner connections.

Implement your authorization flow to retrieve an access token

Once you have set up your application, this is how an authorization flow should be implemented:

  • On your application’s user interface, implement a button that your beneficiaries can click on to initiate our OAuth authorization flow at https://airwallex.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENTID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES
  • Your beneficiaries will be asked to login to Airwallex, choose the account they want to connect to your application, and consent to your application being granted the permission to access their Airwallex account number and account name
  • Once consent is given, they will be redirected back to your redirect URI along with an authorization code that your application can use to exchange for an access token and a refresh token

For more information, read this Implement your authorization flow page for partner connections.

Obtain your beneficiary’s Airwallex account number and account name

With the access token, your application can retrieve your beneficiary’s Airwallex account number and account name by calling the Access own account info API endpoint with Authorization: Bearer <access_token> in the request header.

Example request

Shell

Example response

JSON

Step 2: Create a transfer via Airwallex Pay

Using your beneficiary’s Airwallex account number and account name, you can create a transfer from your own Airwallex account to the beneficiary’s Airwallex account by calling Create a new transfer API.

Please specify the beneficiary type and provide the requied digital wallet details as follows:

  • type: Specify the beneficiary type as DIGITAL_WALLET for Airwallex Pay. The value will default to BANK_ACCOUNT if not specified.
  • digital_wallet: Required beneficiary digital wallet parameters will vary according to the specified digital wallet provider. See Airwallex Pay requirements below.
    • account_name: Specify the beneficiary’s Airwallex account name
    • id_type: Specify account_number for Airwallex Pay
    • id_value: Provide the beneficiary’s Airwallex account number
    • provider: Sepcify AIRWALLEX for Airwallex Pay

Please refer to Step 2 in Create a transfer for further details.

Example request

Shell

Example response

JSON

Errors

Airwallex uses conventional HTTP response codes API to indicate the success or failure of an API request.

A HTTP 400 status code indicates an error that has been triggered due to the information provided in the request. See Error codes to learn about all possible errors associated with the HTTP 400 status when creating a transfer to an Airwallex account.

Step 3: Retrieve a transfer via Airwallex Pay

Please refer to Step 3 in Create a transfer for more details.

What happens on the beneficiary’s side?

When the transfer is sent, the transfer amount is credited to the beneficiary’s wallet balance.

  1. Users of the beneficiary’s Airwallex account can subscribe to email notifications that they receive at the settlement of a transfer to an Airwallex account. An email notification includes the short reference ID, transfer amount, transfer currency, the account name of the payer, and the reference.

  2. Other ways to see Airwallex Pay settlements on the beneficiary’s side:

On this page