Create a payout

• 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 payment methods, delivery times, and other country specific details.
• As a platform, you can call all Payouts 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 payout, you will need to prepare the required beneficiary information, which can vary depending on the payout country/currency, payment method, local clearing system, beneficiary type.

Our dynamic schema API allows you to obtain precise field requirements specific to the intended payout 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 payout 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 payout by specifying the beneficiary_id instead (see Step 2).

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

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 payout 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 payout 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 payment API.

Refer to the dynamic schema API for precise field requirements specific to the intended payout 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:

  • bank_details: Required beneficiary bank account details parameters will vary according to the specified payout 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.

• payment_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 payout. If it is different from payment_currency, an underlying currency conversion will be booked (Refer to Transactional FX for more details).

• payment_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 payout fees applied (if any) are returned as amount_beneficiary_receives and amount_payer_pays in the response. If a payout was initially created and submitted for approval, these amounts are tentative based on the exchange rate at the time of creation until the payment status changes to SCHEDULED, at which point the exchange rate is confirmed. By default, payout fees are charged to the payer i.e. added to payment_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).

• payment_method: Specify SWIFT to create an international SWIFT payout; or LOCAL to create a payout via the local clearing system, which is faster and more cost-effective. See Payout Network for supported payment 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 payout scenarios.

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

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

• fee_paid_by: By default, payout 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.

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

  For payouts with the same source and payment currency, you can specify a date up to 120 days into the future. For payouts with currency conversions, generally you can specify a date up to 2 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 for Australia or Hong Kong customers, but additional regulatory restrictions and application/review process may apply. Please confirm the acceptable value dates by currency pair with your Account Manager.

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

• quote_id: Specify the quote_id returned from a previously created LockFX quote to fix the conversion rate of the payout. You must also ensure that the source_currency and payment_currency in your payout request match the sell_currency and buy_currency from the LockFX quote. By default, MarketFX (the prevailing market rate at the point of conversion) will be applied to the underlying currency conversion. See Transactional FX to learn more about the options you have in performing conversions and how you can leverage the corresponding API endpoints. LockFX quotes cannot be applied for creating and submitting a payout for approval.

• 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 payout (connected account owner in a platform use case), and it is not necessary to specify the payer information.

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