Handle failed transfers (older versions)
This page applies for API version 2023-10-01 or earlier.
After a transfer 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 transfer'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 transfers 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 transfer:
- Retry a transfer. If a transfer 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 transfer below for more details. - Cancel a transfer. If a transfer failed due to reasons other than incorrect beneficiary details (failure code
905XX-999XX, see Failure reasons), or if you would like to amend transfer request parameters other than beneficiary details, you can cancel it by calling Cancel a payment API. Please refer to Cancel a transfer below for more details.
The following table provides guidance on the rules and behaviors subsequent to these actions.
| Retry a transfer | Cancel a transfer | |
|---|---|---|
| Behavior | The status of the failed transfer transitions to RETRIED, while a new transfer with a different payment_id will be created automatically upon successful retry. | The status of the failed transfer will transition to CANCELLED. You may choose to create a new transfer by calling Create a new payment API. |
| Refund | No refund to your Wallet. Transfer amount will be immediately used for the new transfer created upon successful retry. | Transfer 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 transfer amount is immediately used for the new transfer. | Transfer 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 | Transfer fee for the failed transfer will not be refunded. Transfer fee for the new transfer and third-party fee (if any) for the failed transfer will be separately deducted from your Wallet 5 business days after retry. See Fees in retries. | Transfer fee for the failed transfer will not be refunded. Third-party fee (if any) for the failed transfer will be separately deducted from your Wallet 5 business days after cancellation. See Fees in cancellations. |
Retry a transfer
If a transfer is in the FAILED status, you can retry the transfer with updated parameters by calling Retry a payment API. Specify the payment_id of the failed transfer 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 transfer 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 transfer.
After you submit a retry request successfully, the API response will return a new payment_id and all the other transfer details same as in a Create a new payment response. The RETRIED status will be assigned to the failed transfer, 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 transfer. If you have saved your beneficiary with Airwallex and wish to update it with the new parameters before using it for transfers, 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:
- Transfer fee: charged by Airwallex for processing the transfer.
- Third-Party fee (if applicable): charged by our banking partners (local payer banks, SWIFT intermediate/correspondent banks, etc.) for processing the transfer.
This ensures the new transfer with the same amount can be created immediately even if there is insufficient wallet balance to cover these fees.
Cancel a transfer
Whether a transfer is eligible for cancellation depends on its status (see Transfer statuses to learn more about transfer status transitions). Only transfers in NEW or FAILED statuses can be cancelled. If you need to cancel a transfer in exceptional circumstances before it's dispatched (under IN_REVIEWorREADY_FOR_DISPATCH), please contact your Account Manager.
- If a transfer 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 transfer'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 transfer, you can either wait for the auto-cancellation, or actively request via API.
To cancel a NEW or FAILED transfer via API, call Cancel a payment API and specify the unique identifier of the failed transfer (payment_id) in the endpoint URL.
An empty object will be returned if the transfer 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 transfer:
NEW: The whole transfer amount with fees will be refunded.IN_REVIEW/SUSPENDED/READY_FOR_DISPATCH: The transfer amount less transfer fees will be refunded.FAILED: The transfer amount less transfer 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 transfer is cancelled, we will refund the transfer amount (less transfer fees and any applicable third party fees) to your Wallet in the payment currency. However, if a transfer'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”.