Payout retries
Payout retries increase the likelihood that your users with EUR accounts receive payouts instantly, with fallbacks in case instant payouts aren't available.
Payout retries only apply to payments made with the EUR currency.
Retries are enabled for all closed-loop and open-loop payouts by default. This means that any failed payouts are retried for one hour over an instant payment scheme. The final retry is made over a non-instant payment scheme.
This page explains each aspect of payout retries in more depth. Contact us to disable payout retries, or to change the period that payouts are retried for.
Default behaviour, with payout retries enabled
Payout retries are enabled by default. In the default behaviour, payouts are retried over the instant EUR payment scheme for, SEPA Credit Instant Transfer for about an hour (you can change this). The final payout attempt is made over the non-instant EUR payment scheme, SEPA Credit Transfer, to increase the likelihood the payout executes.
Payout retry example
The exact timing for payout retries uses a jittered exponential backoff alogrithm, which means there is not a set schedule.
However, there is generally an average time period after which each payout retry is made.
This table shows the timing of each payout and retry with the default behaviour enabled. The timing of each payout is given in the format of HH:MM:SS
from the initial payout attempt.
Payout attempt | Average payout timing | Worst case payout timing |
---|---|---|
Initial payout attempt over Sepa Instant. | 00:00:00 | 00:00:00 |
Retry 1 over Sepa Instant. | 00:01:32 | 00:03:03 |
Retry 2 over Sepa Instant. | 00:06:06 | 00:12:12 |
Retry 3 over Sepa Instant. | 00:19:50 | 00:39:39 |
Retry 4 over Sepa Instant. | 01:01:00 | 02:02:00 |
Retry 5 over Sepa Credit. | 01:01:01 | 02:02:01 |
In the UK, the API attempts to retry payouts five times over Faster Payments. There is no sixth fallback attempt (as there is no non-instant payment scheme to use).
Disable payout retries
You can contact us to disable payout retries. If disabled, we do not attempt to retry any payouts, and they will either succeed or fail quickly.
Retry duration
By default, payouts are retried for a duration of 1 hour. Contact us to change the duration payouts are retried for to a minimum of 1 minute and a maximum of 1 day.
For the duration you specify, payouts are retried with a jittered exponential backoff algorithm. This means that payouts are initially retried more frequently, and grow progressively further apart.
However, the exponential nature of retries stops at 3 hours from the original payout. After three hours, each retry is made 3 hours after the previous retry. The final retry can be attempted after the duration you specify. For example, if you set a duration of 7 hours and a payout occurred at 6 hours, the final payout would be made at 9 hours.
Payout status during retries
For the duration that a payout is retried, the payout status changes back and forth between pending
and authorized
.
You can check the status of a payout that is being retried with the /v3/payouts/{id}
endpoint.
Webhook notifications for payout retries
After you initiate a payout, you don't receive any webhook notifications until the payout enters one of the two terminal statuses of executed
or failed
. In this case, you receive the payout_executed
or payout_failed
webhook.
As a result, in the case of payout failure, you will not receive a webhook notification until the retries have finished.
Updated 5 months ago