Smart Dunning retries
Beta
Last updated: July 30, 2025
Checkout.com's Smart Dunning retry solution improves payment recovery for failed merchant-initiated transactions (MITs) by intelligently predicting and scheduling retries at optimal times. The optimal schedule is determined by:
- Analyzing payment network data, including customer locations, payment amounts, issuing banks, and historical customer behavior patterns
- Leveraging advanced machine learning algorithms
- Monitoring real-time network alerts
You can set up an automated Smart Dunning retry schedule for recurring or unscheduled MITs that are soft declined with one of the following response codes:
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've configured your webhook receiver, you receive a payment_retry_scheduled
webhook when an MIT fails and a retry is scheduled.
Information
You must be integrated directly with Checkout.com to enable automatic payment retries. Integrations via a third-party are not eligible.
You can specify the following parameters of a retry schedule:
- How many times you want us to retry the payment
- The number of days over which you want us to perform the payment retries
To set global parameters for all of your eligible payments, contact your account manager or request changes.
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
1{2"source": {3"type": "card",4"name": "test",5"expiry_month": 12,6"expiry_year": 2029,7"cvv": "422",8"number":"4242424242424242"9},10"3ds": {11"enabled": false12},13"retry": {14"dunning": {15"enabled": true,16"end_after_days": 21,17"max_attempts": 418}19},20"amount": 100,21"currency": "GBP",22"capture": false,23"merchant_initiated": true,24"payment_type": "Recurring",25"processing_channel_id": "pc_lseidaphwziubknx6sbfifq6dq"26}
If the payment authorization is soft declined and you set up a retry schedule, you receive information about the next scheduled retry in the payment response's retry
object.
1{2"id": "pay_foyki4polp7upkooyx3xnvfcca",3"action_id": "act_sgr6fxcobgwutjhfggsvyx7rie",4"amount": 100,5"currency": "GBP",6"approved": false,7"status": "Retry Scheduled",8"response_code": "20051",9"response_summary": "Insufficient Funds",10"retry": {11"max_attempts": 2,12"next_attempt_on": "2023-11-27T12:59:31.5797568Z",13"ends_on": "2023-11-28T12:59:18.1914252Z"14},15"processed_on": "2023-11-27T12:59:21.645231Z",16"_links": {17"self": {18"href": "https://api.sandbox.checkout.com/payments/pay_foyki4polp7upkooyx3xnvfcca"19},20"actions": {21"href": "https://api.sandbox.checkout.com/gateway/payments/pay_foyki4polp7upkooyx3xnvfcca/actions"22},23"cancel": {24"href": "https://api.sandbox.checkout.com/gateway/payments/pay_foyki4polp7upkooyx3xnvfcca/cancellations"25}26}27}
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.
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"reference": "ORD-5023-4E89"4}
To simulate a retry schedule in the sandbox environment, call the Request a payment endpoint and set the retry.dunning
field to true
.
The system performs three retries at 30-second intervals. The outcome of the final retry depends on the amount
value you provide:
- If
amount
is greater than1000
, the final attempt succeeds. - If
amount
is less than1000
, the final attempt fails.
You can control the soft decline reason for the attempts in the retry schedule by using one of the following Visa test cards as the source
:
Soft decline reason | Card number |
---|---|
Insufficient funds |
|
Do not honour |
|
Activity amount limit exceeded |
|
Blocked |
|