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
Manage approvals for payouts Handle failed payouts
Failure reasons
Payouts to countries/regions with capital controls
Create a payout to an Airwallex account
Embedded Payout component
Test and go live
Older API versions

Handle failed payouts

This page describes how to handle failed payouts for API version 2024-01-31 or later. For older API versions, please see Handle failed payouts (older versions).

After a payout has been SENT, it may fail our banking partner’s processing or be rejected by the recipient bank, at which point its status will transition to FAILED. Subscribe to payment.failed webhook events to receive real-time notifications of each payout's failure, and retrieve failure reasons by calling Get payment by ID API or Get list of payments API.

See Failure reasons for all possible failures and recommended actions. Please note that failed payouts will be automatically cancelled after a certain time depending on the region you are in. Please reach out to your Account Manager to find out more.

Alternatively, you can Cancel a payment API and create a new one with updated parameters.

Cancel a payout

To cancel a payout, you can call Cancel a payment API and specify the unique identifier of the failed payout (payment_id) in the endpoint URL. Whether a payout is eligible for cancellation depends on its status (see Payout statuses to learn more about payout status transitions).

  • If a payout is cancelled before SENT, its status will transition to CANCELLED_REQUESTED, and then to CANCELLED when successfully refunded.
  • For FAILED payouts, if you wish to cancel, you can either wait for the auto-cancellation as mentioned above, or actively request via API.

An empty object will be returned if the payout has been successfully cancelled.

Example request

Shell

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.

Refund and Fees

After a payout is cancelled, the payout amount (less any applicable fees) will be refunded to your Wallet. You can retrieve the updated Wallet balance via Get Current Balances API.

For payout with currency conversion, it can be refunded in either source or payment currency, depending on your account setting. Please reach out to your Account Manager to find out more.

  • Refund in payment currency (Default): Upon cancellation, the payout amount (less any applicable fees) will be refunded to your Wallet in the payment currency. For certain exotics currencies that cannot be held in the Wallet, the funds will be adjusted back in the source currency. See Currency conversion in cancellations.
  • Refund in source currency: Upon cancellation, the payout amount (less any applicable fees) will be refunded to your Wallet in the source currency. Particularly a FX cancellation delta fee is applicable in the event that the market rate has moved from the rate of the original conversion (see Conversion amendments for details).

Fees in cancellations

There are three types of fees that may apply to payout cancellation.

  • Payout fee will only be refunded upon payout cancellation if funding has not begun processing.
  • Third-party fee is deducted by the external bank from the refunded amount for processed payouts which subsequently failed. Upon payout cancellation, this fee will be separately deducted from your Wallet after 5 business days.
  • FX cancellation delta fee is applicable in the event that the market rate has moved from the rate of the original conversion. Upon payout cancellation, this fee will be separately deducted from your Wallet after 5 business days.

How fees will be charged for a cancellation depends on the payout status:

  • SCHEDULED: Full payout amount or payout amount less payout fee will be refunded depending on whether funding has begun processing. FX cancellation delta fee may apply.
  • OVERDUE: Only FX cancellation delta fee may apply because funding has not been received.
  • PROCESSING: Payout amount less payout fee will be refunded. FX cancellation delta fee may apply.
  • FAILED: Payout amount less payout fee will be refunded. Third-party and FX cancellation delta fees may apply.

Currency conversion in cancellations

When a payout is cancelled, we will refund the payout amount (less payout fees and any applicable third party fees) to your Wallet in the payment currency. However, if a payout's payment currency is an exotic currency (IDR, MYR, PHP, TRY, INR, VND, BDT, LKR, NPR, PKR, BHD, EGP, MAD, CLP, ARS, BRL, COP, BOB, PEN, and UYU) that cannot be held in your Wallet, the refunded amount will be adjusted from your Wallet back into an equivalent amount in the source currency under the transaction type “ADJUSTMENT”.

On this page
  • Cancel a payout
  • Refund and Fees