Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Create beneficiaries
Validate a beneficiaryRetrieve beneficiariesManage beneficiariesUsing API and form schemas Embedded Beneficiary component
Test and go live
Older API versions

Create beneficiaries

Call Create a new beneficiary API to save and manage beneficiaries that you can use for creating payouts using beneficiary_id.

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.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. The street_address must not be a P.O. box address.
  • beneficiary.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.
  • beneficiary.entity_type: Specify whether the beneficiary is an individual (PERSONAL) or a business (COMPANY).
  • beneficiary.company_name, OR beneficiary.first_name and beneficiary.last_name: The beneficiary’s name according to the entity_type.
  • beneficiary.payment_methods: 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.
  • beneficiary.additional_info.personal_email (Optional): 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.

Example request


If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.

Example response