Create a batch 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 payment methods, delivery times, and other country specific details.
• As a platform, you can call all Batch 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.

Call Create a batch transfer API with the required funding source and batch information (name, remarks, request id, transfer date) to create a batch transfer. Please find below further considerations on some of the parameters:

• funding_source: funding source details should only be provided in this object if the batch transfer is to be funded via direct debit from Linked Account. Do not specify any parameters for Wallet as the funding source.

  • id: Unique ID of your Linked Account as returned in Create a Linked Account API.
  • deposit_type: Should be either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. Deposit type will default to DIRECT_DEBIT if not specified. See direct debit flight times to understand difference between the two deposit types.

• transfer_date: current or future date (ISO 8601 format) for when the batch transfer should be processed if using Wallet as the funding source. If left blank, the transfer date will default to the earliest possible date. Please note that transfer_date cannot be specified when Linked Account is used as the funding source.

  Transfer items with the same source and payment currency can support transfer dates up to 120 days into the future; whereas transfer items with currency conversions can support transfer dates up to 2 days into the future (varies by currency pairs). Longer tenors up to 180 days (varies by currency pair) are possible with our FX forwards product for Australian 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. Since all transfer items within a batch are scheduled to a single transfer date, you may get validation errors for transfer items due to invalid transfer dates.

  For batch transfers with approval flows, the transfer_date will be updated if it was approved after the original specified date; at which point the batch transfer status transitions to SCHEDULED and transfer_date is fixed.

In the response, you will see the batch transfer status is DRAFTING. Next, you can add transfer items (Step 3) to the batch you just created.

Before adding transfer items to a batch, 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 adding transfer items to a batch by specifying the beneficiary_id instead (see Step 3).

After creating a batch transfer, you can call Add items to a batch API to add transfer items to a batch. You may add a maximum of 100 transfer items at a time, up to a maximum total of 1,000 transfer items per batch.

Each batch transfer item requires the same information required to create a payout. Please refer to Step 2 in Create a payout for further details. Note that you do not need to specify payment_date for each item as the transfer_date is set at the batch transfer level. If your funding source is a Linked Account, please make sure to specify the same source_currency for all items in the batch.

After adding valid transfer items to the batch, you can call Quote a batch transfer API to get quotes to lock the conversion rates for valid items in the batch. Please note that this is not a required step.

• If you have quoted before submitting the batch. You must always ensure to submit before the quotes expire; otherwise, you will receive a quote_expired error. In that case, you can call quote a batch transfer to obtain a new quote and submit the batch again;
• If you have not quoted before submitting the batch, all transfer items will be quoted automatically upon submission and you can see the quote details in the response.

For batch transfers with approval flows, quotes will be updated if the batch transfer is approved after the quote expires; at which point the batch transfer status transitions to SCHEDULED, and quotes are fixed.

In the response, you will see a quote_summary with the following useful parameters:

• expires_at: The expiration time of the quotes
• quotes: Details of each quote based on currency pairs

Call List all items within a batch API to preview all items added to the batch transfer. You can call this endpoint at any time, before or after submitting the batch. Please note that this is not a required step.

Before submitting a batch transfer, i.e. the batch transfer status is DRAFTING, you can call Delete items within a batch API with item_ids to delete invalid or wrong items in the batch. Please note that this is not a required step.

Once you have added valid items to the batch transfer, you can call Submit a batch transfer API to submit the batch.

• If no approval is required, this batch will transition to SCHEDULED status and will be processed by Airwallex accordingly.
• If approval is required, this batch will transition to IN_APPROVAL status.

In the response, you will see a funding object contains the following funding information:

• deposit_type: If specified when creating the batch, the value can be DIRECT_DEBIT or FASTER_DIRECT_DEBIT.
• failure_reason: If there is an error with the funding source, a failure reason will be returned. See Batch transfer direct debit deposit errors (async) for details.
• funding_source_id: The unique ID of your Linked Account if funded by DIRECT_DEBIT or FASTER_DIRECT_DEBIT.
• status: The funding status of this batch transfer. Please see details in Funding Statuses.

After submitting the batch transfer, please ensure sufficient balance is available in your Wallet or Linked Account to cover the batch transfer amount (including fees). Once the batch is successfully funded, the system will start to book single payouts, which can be retrieved by calling Get payment by ID API. See Payout statuses for further details of each payout item.