Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Payouts
Create a payout
Validate a payoutManage payouts
Payouts to countries/regions with capital controls
Create a payout to an Airwallex account
Payout to an Airwallex account statuses
Embedded Payout component
Test and go live
Older API versions

Create a payout to an Airwallex account

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

Creating a payout to an Airwallex account to be routed through the transfer approval workflow set up on the Airwallex account is currently not supported.

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 payout 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 payout to an Airwallex account

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

Note that you can currently only create a payout to an Airwallex account without currency conversions. Also, future dated payout to an Airwallex account is not supported.

Fund deduction

Funds will be immediately deducted from the Wallet upon payout creation. Please ensure that you have sufficient balance in your Wallet when creating payouts. Payout to an Airwallex account currently does not support the post-fund model (see Funding and settlement models).

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 payout to an Airwallex account.

Step 3: Retrieve a payout to an Airwallex account

Retrieve payouts to Airwallex accounts by calling Get a wallet transfer by ID API or Get list of wallet transfers API to view statuses and other details. Additionally, you can subscribe to Payouts webhook events to receive any payout status transitions. See Payout to an Airwallex account statuses for more information.

Retrieve a payout to an Airwallex account

Call Get a wallet transfer by ID API to retrieve details of a payout to an Airwallex account by specifying the wallet_transfer_id. A successful request will return a response in the same format as Create a new wallet transfer API.

Retrieve a list of payouts to Airwallex accounts

Call Get list of wallet transfers API to retrieve a list of payouts to an Airwallex account. You can specify the date range of payout creation (from_created_at and to_created_at, inclusively) as parameters in the request. You can also use other optional parameters such as transfer_currency and status to filter the list, and the pagination parameters (page, page_size) to refine the results.

Example response

JSON

What happens on the beneficiary’s side?

When the payout is settled, 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 payout 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 the settlement of a payout to an Airwallex account on the beneficiary’s side:

On this page