Configure scheduled retries
Last updated: November 20, 2024
You can set up an automated retry schedule for recurring or unscheduled merchant-initiated transactions (MITs) that are soft declined with one of the following responses:
20005 - Declined - Do Not Honour20051 - Insufficient Funds20061 - Exceeds Withdrawal Value/Account Limits20078 - Blocked, first use - transaction from new cardholder and card not properly unblocked
Additionally, you can enable automatic downtime retries to retry MITs that fail due to an issuer or acquirer network timeout.
If an MIT fails and a retry is scheduled, you'll receive a payment_retry_scheduled webhook.
Note
If you've implemented a custom retry solution in your backend, verify the payment response to check if an automatic retry was already initiated before you attempt your own.
If you enable automatic downtime retries, we will automatically retry any MITs that fail due to an issuer or acquirer network timeout. This applies to MITs that return any of the following response codes:
20068 - Response received too late / Timeout / Internal error20091 - Issuer unavailable or switch is inoperative20096 - System malfunction
Information
To enable automatic downtime retries, contact your Account Manager or [email protected].
You can specify the following parameters of a retry schedule:
- how many times we should retry the payment
- the number of days over which we should perform the payment retries
Payment retries will be attempted at exponentially increasing intervals over the period of time you specify. For example, a schedule with three attempts over 30 days could result in the following:
- the first retry would be attempted 7 days after the original authorization request
- the second retry would be attempted 9 days after the first retry
- the final retry would be attempted 14 days after the second retry
To set global parameters for all of your eligible payments, contact your Account Manager or [email protected].
Information
You must be integrated directly with Checkout.com to enable automatic payment retries. Integrations via a third-party are not eligible.
Alternatively, you can specify a retry schedule for an individual payment by passing the retry object in the payment request:
post
https://api.checkout.com/payments
If the payment authorization is soft declined and you set up a retry schedule, you'll receive information about the next scheduled retry in the payment response's retry object
If you've enabled webhook notifications, you'll also receive an equivalent retry object in your payment_approved or payment_declined webhook notification.
Whenever a payment retry attempt fails, you'll receive a payment_retry_scheduled webhook with more information about the retry schedule.
To review the status of the retry schedule, call the Get payment details endpoint.
To make it easier to correlate your transaction history, all retry attempts within the same retry schedule share a payment ID. There may be multiple authorization actions associated with a single pay_ ID.
To view the full history of the payment retry schedule, call the Get payment actions endpoint.
Additionally, you can review declined payments with retry schedules in the Dashboard.
- Sign in to the Dashboard.
- Navigate to Payments > All payments, to review all your payments.
- The payments with a scheduled retry have a Retry scheduled label next to their status.
When you select a declined payment, you can review its payment details and the payment's timeline of events.
When all scheduled retries complete, the payment status updates to one of the following values:
- Declined: the final retry was hard declined.
- Approved: the final retry was approved.
- Refunded: the final retry resulted in a refund
You can cancel a retry schedule at any point before it expires.
To cancel a retry schedule, call the following endpoint with the payment id returned in the Get payment details response:
post
https://api.checkout.com/payments/{id}/cancellations
Information
The Payments API supports idempotency. You can safely retry API requests without the risk of duplicate requests.
To simulate a retry schedule in your test environment, include the following in your sandbox payment request:
- the
retryobject, with its fields configured - the
amountfield – this is the number of attempts that should be performed before the test payment is approved or hard declined
You must also use one of the test cards from the following table as the payment source. The card you choose determines:
- the soft decline reason for the attempts in the retry schedule
- whether the final attempt is approved or hard declined
| Soft decline reason | Card scheme | Card number |
|---|---|---|
Insufficient funds | Visa |
|
Do not honour | Visa |
|
Activity amount limit exceeded | Visa |
|
Blocked | Visa |
|
Each payment retry will be attempted at 30-second intervals.