Handle failed transfers
This page describes how to handle failed transfers for API version 2024-01-31 or later. For older API versions, please see Handle failed transfers (older versions).
After a transfer 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 payout.transfer.failed webhook events to receive real-time notifications of each transfer's failure, and retrieve failure reasons by calling Get transfer by ID API or Get list of transfers API.
See Failure reasons for all possible failures and recommended actions. Please note that failed transfers will be automatically cancelled in seconds.
Alternatively, you can Cancel a transfer API and create a new one with updated parameters.
Cancel a transfer
To cancel a transfer, you can call Cancel a transfer API and specify the unique identifier of the failed transfer (transfer_id) in the endpoint URL. Whether a transfer is eligible for cancellation depends on its status (see Transfer statuses to learn more about transfer status transitions).
- If a transfer is cancelled before
SENT, its status will transition toCANCELLED_REQUESTED, and then toCANCELLEDwhen successfully refunded. - For
FAILEDtransfers, 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 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.
Refund and Fees
After a transfer is cancelled, the transfer amount (less any applicable fees) will be refunded to your Wallet. You can retrieve the updated Wallet balance via Get Current Balances API.
For transfer with currency conversion, it can be refunded in either source or transfer currency, depending on your account setting. Please reach out to your Account Manager to find out more.
- Refund in transfer currency (Default): Upon cancellation, the transfer amount (less any applicable fees) will be refunded to your Wallet in the transfer 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 transfer 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 transfer cancellation.
- Transfer fee will only be refunded upon transfer cancellation if funding has not begun processing.
- Third-party fee is deducted by the external bank from the refunded amount for processed transfers which subsequently failed. Upon transfer cancellation, this fee will be separately deducted from your Wallet.
- FX cancellation delta fee is applicable in the event that the market rate has moved from the rate of the original conversion. Upon transfer cancellation, this fee will be separately deducted from your Wallet.
How fees will be charged for a cancellation depends on the transfer status:
SCHEDULED: Full transfer amount or transfer amount less transfer 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: Transfer amount less transfer fee will be refunded. FX cancellation delta fee may apply.FAILED: Transfer amount less transfer fee will be refunded. Third-party and FX cancellation delta fees may apply.
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 refund currency you set. However, if a transfer's transfer currency is an exotic currency that cannot be held in your Wallet, the transfer amount (less any applicable fees) will always be refunded in the source currency and an FX delta will apply.