Create a transfer

• 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.
• Check out Payout Network for supported regions and currencies, and the country guides under it for more details on transfer methods, delivery times, and other country specific details.
• As a platform, you can call all Transfers API endpoints on behalf of your connected accounts by specifying the connected account's open ID (in the format acct_xxxxxx) 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 Global Finance.

Before creating a transfer, you will need to prepare the required beneficiary information, which can vary depending on the transfer country/currency, transfer method, local clearing system, beneficiary type.

Our dynamic schema API allows you to obtain precise field requirements specific to the intended transfer scenario. Refer to the screenshot below on which fields you can specify to generate the schema.

The dynamic schema comes in handy when you are checking for a handful of transfer scenarios. To obtain our full schema for beneficiaries programmatically in a JSON payload, you can call Get the API schema API to retrieve the required fields and validation rules, and/or Get the form schema API to retrieve suggested specifications on the UI components to render the fields along with the corresponding validation rules. See Using API and form schemas to learn more.

Furthermore, beneficiary information can be saved beforehand and used directly when creating a transfer by specifying the beneficiary_id instead (see Step 2).

Call Create a new transfer API with the required beneficiary and transaction information (currency, amount, date, reference) to create a transfer.

Beneficiary information can be specified within the request in two ways:

1. Beneficiary ID

   If you prefer to save beneficiary information with Airwallex in advance to simplify the transfer creation process, you can call Create a new beneficiary API, and a unique beneficiary_id will be returned. This can be used in place of the beneficiary object to create the transfer subsequently.

   See Create beneficiaries and Manage beneficiaries to learn more.

2. Directly within the request

   If you prefer to manage all beneficiary information outside of Airwallex, you can provide beneficiary information directly under the beneficiary object each time when calling Create a new transfer API.

Refer to the dynamic schema API for precise field requirements specific to the intended transfer scenario. If you specify a parameter that is either not required or not on the full schema, it will be ignored and removed from the response. Please find below further considerations on some of the required parameters:

• beneficiary: beneficiary details should be provided directly in this object if beneficiary_id is not used:

  • type: Specify whether the beneficiary type is a BANK_ACCOUNT or a DIGITAL_WALLET (including Airwallex Pay). The value will default to BANK_ACCOUNT if not specified.
  • bank_details or digital_wallet: Required beneficiary bank account details or digital wallet parameters (depending on the type specified), varies according to the specified transfer scenario. Please refer to dynamic schema API or call Get the API schema API to obtain the corresponding parameter requirements.
  • address: required address parameters such as street address, city, state and postcode will vary according to the specified address country. Please refer to dynamic schema API or call Get the API schema API to obtain the corresponding parameter requirements.
  • entity_type: Specify whether the beneficiary is an individual (PERSONAL) or a business (COMPANY).
  • company_name, OR first_name and last_name: The beneficiary’s name according to the entity_type.

• transfer_currency: The currency (3-letter ISO 4217 code) in which the beneficiary receives. It must match account_currency of the beneficiary’s bank account details. See Payout Network for supported currencies.

• source_currency: The currency (3-letter ISO 4217 code) in which to fund the transfer. If it is different from transfer_currency, an underlying currency conversion will be booked (Refer to Transactional FX for more details).

• transfer_amount OR source_amount: Please only specify one of these two amounts in their respective currencies. The other amount will be calculated and returned in the response.

  Actual amounts with transfer fees applied (if any) are returned as amount_beneficiary_receives and amount_payer_pays in the response. If a transfer was initially created and submitted for approval, these amounts are tentative based on the exchange rate at the time of creation until the transfer status changes to SCHEDULED, at which point the exchange rate is confirmed. By default, transfer fees are charged to the payer i.e. added to transfer_amount and resulted in amount_payer_pays. If you wish to pass on the fees to the beneficiary, you can specify using the fee_paid_by parameter (see below for more details).

• transfer_method: Specify SWIFT to create an international SWIFT transfer; or LOCAL to create a transfer via the local clearing system, which is faster and more cost-effective. See Payout Network for supported transfer methods by countries/regions and currencies.

• reference: A user-specified reference that may be displayed to the beneficiary on their bank statement, depending on whether this is supported by the local clearing system and our banking partners. Contact your Account Manager to confirm whether display of reference is supported for your transfer scenarios.

In addition, you may also choose to specify the following optional parameters in your request to further customize the transfer or leverage other related features:

• beneficiary.additional_info.personal_email: Specify this parameter if you want the beneficiary to receive an email notification upon transfer being dispatched. Please contact your Account Manager to enable this feature beforehand.

• fee_paid_by: By default, transfer fees will be charged to the PAYER and included in the amount_payer_pays within the response. If you wish to pass on the fees to the beneficiary, set the value to BENEFICIARY.

• swift_charge_option: By default, SHARED will be applied, in which case the SWIFT charges will be shared between the payer and the beneficiary, i.e. the beneficiary will receive the amount_beneficiary_receives less corresponding SWIFT charges by the beneficiary bank. If you want the beneficiary to receive the full amount_beneficiary_receives, set the value to PAYER to cover the additional SWIFT charges.

• transfer_date: Specify a current or future date (ISO 8601 format) for when the transfer should be processed. If left blank, the transfer date will default to the earliest possible date and your transfer will be dispatched as soon as possible.

  For transfers with the same source and transfer currency, you can specify a date up to 180 days into the future. For transfers with currency conversions, generally you can specify a date up to 90 days into the future (varies by currency pairs). Longer tenors up to 180 days (varies by currency pair) is possible with our FX forwards product. Please confirm the acceptable value dates by currency pair with your Account Manager.

  For transfers created and submitted for approval, the transfer_date will be updated if it was approved after the original specified date; at which point the transfer status transitions to SCHEDULED and transfer_date is fixed. The date when the transfer is SENT will be returned in dispatch_date.

• lock_rate_on_create: Specify whether to lock the conversion rate for a future-dated transfer upon creation. This field should only be specified for transfers with currency conversions. The value will default to TRUE if not specified.

  • If TRUE: The transfer is created with a confirmed conversion rate. A prepayment (amount varies by currency pair and tenor) is held upfront to cover any FX delta fee in the event of transfer cancellation, and the full amount will be deducted on the scheduled transfer_date. Further details are returned under the prepayment object.

  • If FALSE: The transfer is created with an unconfirmed conversion rate, which will be confirmed on the scheduled transfer_date, when the full amount will be deducted.

    See Fund deduction for more details.

• quote_id: Specify the quote_id returned from a previously created quote to fix the conversion rate of the transfer. You must also ensure that the source_currency and transfer_currency in your transfer request match the sell_currency and buy_currency from the quote. Quotes cannot be applied for creating and submitting a transfer for approval.

  If not specified, the system will automatically book the underlying currency conversion based on transfer_date and lock_rate_on_create parameters. See Transactional FX to learn more about the options you have in performing conversions and how you can leverage the corresponding API endpoints.

• payer or payer_id: Specify the payer information other than the Airwallex account owner with POBO (Pay On Behalf Of) enabled on a case-by-case approval basis. Similar to beneficiaries, the payer information may be provided directly within the payer object, or by specifying the payer_id of a saved payer. See Create a payer for more information. By default, Airwallex identifies the payer as the Airwallex account owner creating the transfer (connected account owner in a platform use case), and it is not necessary to specify the payer information.

Call Get transfer by ID API or Get list of transfers API to retrieve transfer details. Additionally, you can subscribe to Transfers webhook events to receive any transfer status transitions (the payload will be in the same manner as Create a new transfer API). See Transfer statuses for more information.