Handle failed payouts (older versions)
This page applies for API version 2023-10-01 or earlier.
After a payout has been DISPATCHED, 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 reasonses 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.
There are 2 options to handle a failed payout:
- Retry a payout. If a payout failed due to incorrect beneficiary details (failure code
901XX-904XX, see Failure reasons), you can retry it by calling Retry a payment API with the updated parameters. Please refer to Retry a payout below for more details. - Cancel a payout. If a payout failed due to reasons other than incorrect beneficiary details (failure code
905XX-999XX, see Failure reasons), or if you would like to amend payout request parameters other than beneficiary details, you can cancel it by calling Cancel a payment API. Please refer to Cancel a payout below for more details.
The following table provides guidance on the rules and behaviors subsequent to these actions.
| Retry a payout | Cancel a payout | |
|---|---|---|
| Behavior | The status of the failed payout transitions to RETRIED, while a new payout with a different payment_id will be created automatically upon successful retry. | The status of the failed payout will transition to CANCELLED. You may choose to create a new payout by calling Create a new payment API. |
| Refund | No refund to your Wallet. Payout amount will be immediately used for the new payout created upon successful retry. | Payout amount (less any applicable fees) will be refunded to your Wallet. You can retrieve the updated Wallet balance via Get current balances API. |
| Currency conversion | No additional conversion because the refunded payout amount is immediately used for the new payout. | 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. |
| Fees | Payout fee for the failed payout will not be refunded. Payout fee for the new payout and third-party fee (if any) for the failed payout will be separately deducted from your Wallet 5 business days after retry. See Fees in retries. | Payout fee for the failed payout will not be refunded. Third-party fee (if any) for the failed payout will be separately deducted from your Wallet 5 business days after cancellation. See Fees in cancellations. |
Retry a payout
If a payout is in the FAILED status, you can retry the payout with updated parameters by calling Retry a payment API. Specify the payment_id of the failed payout in the endpoint URL and include updated beneficiary information. Please note that you can only amend a limited set of the original parameters as part of a retry.
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.
A successful request will create a new payout with the updated parameters. If you do not specify any value for a parameter, the retry will use what was originally submitted in the failed payout.
After you submit a retry request successfully, the API response will return a new payment_id and all the other payout details same as in a Create a new payment response. The RETRIED status will be assigned to the failed payout, which is an end state.
Please note that calling Retry a payment API with updated beneficiary details will only change the parameters you use in the new payout. If you have saved your beneficiary with Airwallex and wish to update it with the new parameters before using it for payouts, you should call Update existing beneficiary API.
Fees in retries
Upon a successful retry, the following fees will be deducted from your Wallet after 5 business days:
- Payout fee: charged by Airwallex for processing the payout.
- Third-Party fee (if applicable): charged by our banking partners (local payer banks, SWIFT intermediate/correspondent banks, etc.) for processing the payout.
This ensures the new payout with the same amount can be created immediately even if there is insufficient wallet balance to cover these fees.
Cancel a payout
Whether a payout is eligible for cancellation depends on its status (see Payout statuses to learn more about payout status transitions). Only payouts in NEW or FAILED statuses can be cancelled. If you need to cancel a payout in exceptional circumstances before it's dispatched (under IN_REVIEWorREADY_FOR_DISPATCH), please contact your Account Manager.
- If a payout is cancelled before
DISPATCHED, its status will transition toCANCELLED. However, if the underlying currency conversion has not settled, its status will first transit toCANCELLATION_REQUESTED, and then toCANCELLEDuntil the conversion is settled. - If a payout's status is
FAILED, it 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. If you wish to cancel the failed payout, you can either wait for the auto-cancellation, or actively request via API.
To cancel a NEW or FAILED payout via API, call Cancel a payment API and specify the unique identifier of the failed payout (payment_id) in the endpoint URL.
An empty object will be returned if the payout has been successfully cancelled.
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.
Fees in cancellations
How fees will be charged for a cancellation depends on the status of the payout:
NEW: The whole payout amount with fees will be refunded.IN_REVIEW/SUSPENDED/READY_FOR_DISPATCH: The payout amount less payout fees will be refunded.FAILED: The payout amount less payout fees will be refunded. A third-party fee from the banking partner may apply, and will be deducted from your Wallet after 5 business days.
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”.