# Smart Dunning retries

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](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details.md) or [unscheduled](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/unscheduled-payments-with-stored-card-details.md) MITs that are soft declined with one of the following response codes:

**Eligible response codes**

- `20005` – Declined - Do not honour
- `20013` – Invalid value/amount
- `20014` – Invalid account number (no such number)
- `20015` – Transaction cannot be processed through debit network
- `20016` – Card not initialised
- `20020` – Invalid response
- `20022` – Suspected malfunction
- `20030` – Format error
- `20051` – Insufficient funds
- `20057` – Transaction not permitted to cardholder
- `20057` – Domestic debit transaction not allowed (Regional use only)
- `20061` – Activity amount limit exceeded
- `20065` – Exceeds Withdrawal Frequency Limit
- `20068` – Response received too late / Timeout
- `20068` – Internal error
- `20078` – Blocked at first use - transaction from new or replacement card that is not properly unblocked
- `20096` – System malfunction
- `20098` – MAC error
- `200P1` – Over daily limit
- `20104` – Gateway reject - Invalid transaction
- `20105` – Gateway reject - Violation

> **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 server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), you receive a [Payment retry scheduled](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_retry_scheduled.md) webhook when an MIT fails and a retry is scheduled.

---

## Set up a retry schedule

> **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](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

Alternatively, you can specify a retry schedule for an individual payment by passing the `retry` object in the [payment request](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=0/retry&t=request):

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "card",
    "name": "test",
    "expiry_month": 12,
    "expiry_year": 2029,
    "cvv": "422",
    "number":"4242424242424242",
    "stored": true
  },
  "3ds": {
    "enabled": false
  },
  "retry": {
    "dunning": {
      "enabled": true,
      "end_after_days": 21,
      "max_attempts": 4
    }
  },
  "amount": 100,
  "currency": "GBP",
  "capture": false,
  "merchant_initiated": true,
  "payment_type": "Recurring",
  "processing_channel_id": "pc_lseidaphwziubknx6sbfifq6dq",
  "previous_payment_id": "pay_cr4hxwizzp6k7biycuk2ibltnm"
}
```

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.

### Response example

```json
{
  "id": "pay_foyki4polp7upkooyx3xnvfcca",
  "action_id": "act_sgr6fxcobgwutjhfggsvyx7rie",
  "amount": 100,
  "currency": "GBP",
  "approved": false,
  "status": "Retry Scheduled",
  "response_code": "20051",
  "response_summary": "Insufficient Funds",
  "retry": {
    "max_attempts": 2,
    "next_attempt_on": "2023-11-27T12:59:31.5797568Z",
    "ends_on": "2023-11-28T12:59:18.1914252Z"
  },
  "processed_on": "2023-11-27T12:59:21.645231Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_foyki4polp7upkooyx3xnvfcca"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/gateway/payments/pay_foyki4polp7upkooyx3xnvfcca/actions"
    },
    "cancel": {
      "href": "https://{prefix}.api.sandbox.checkout.com/gateway/payments/pay_foyki4polp7upkooyx3xnvfcca/cancellations"
    }
  }
}
```

If you've subscribed to webhooks, you also receive an equivalent `retry` object in your `payment_approved` or `payment_declined` webhook.

Whenever a payment retry attempt fails, you receive a [Payment retry scheduled](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_retry_scheduled.md) webhook with more information about the retry schedule.

---

## Review retry schedules

To review the status of the retry schedule, call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) 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](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentActions) endpoint.

Additionally, you can review declined payments with retry schedules in the Dashboard:

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Payments_ > _All payments_. <br>
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.

We stop future retries if the payment declines with:

- A `03` [recommendation code](https://www.checkout.com/docs/developer-resources/codes/recommendation-codes.md) not to retry the payment
- A response code that is not eligible for Smart Dunning retries

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

---

## Cancel a retry schedule

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](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) response:

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/{id}/cancellations`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/cancellations`

> **Information**
>
> The Payments API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests.

### Response example

```json
{
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "reference": "ORD-5023-4E89"
}
```

---

## Create a test retry schedule

To simulate a retry schedule in the sandbox environment, call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint, setting:

- The `retry.dunning` field to `true`.
- The `processing.pan_preference` field to `fpan`.

Checkout.com automatically performs three retries at 30-second intervals.

Use one of the following Visa test cards as the `source` to control the final outcome of the retry schedule:

| Test scenario | Card number |
| --- | --- |
| Retries end with a successful payment | `4658587554931538` |
| Retries end with a declined payment | `4795395028309255` |