***

title: Dunning & Payment Recovery
subtitle: Recover failed payments and reduce involuntary churn
slug: payments-recovery/dunning-payment-recovery
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/payments-recovery/llms.txt. For full documentation content, see https://docs.prolifi.io/payments-recovery/llms-full.txt.

## What this covers

This reference document covers Prolifi's dunning and payment recovery system -- what dunning is, why it matters for revenue retention, how to configure the retry logic and communication workflow, and how to integrate the dunning outcome into your application. Effective dunning configuration is one of the most direct levers available to reduce involuntary churn and recover revenue that would otherwise be lost.

***

## Prerequisites

<Note>
  Before configuring dunning:

  * Payment gateway is connected (dunning requires a gateway to retry against). See [Getting Started: Finance](/getting-started/finance).
  * Communication settings are configured (email templates for dunning emails). See [Getting Started: Finance](/getting-started/finance).
  * Subscriptions exist (dunning applies at the subscription level).
</Note>

***

## 1. What Dunning Is and Why It Matters

**Dunning** (see [Glossary: Billing Terms](/glossary/billing-terms)) is the process of automatically attempting to recover a payment that initially failed -- through a configured sequence of payment retries, customer communications, and (if retries are exhausted) subscription lifecycle actions.

### 1.1 The problem dunning solves

When a customer's payment method is charged and the charge fails, there are two paths:

* **Without dunning:** The invoice remains unpaid. The subscription is cancelled (or access is revoked) immediately. The customer may not know the payment failed. The business loses the customer and the revenue -- this is **involuntary churn** (see [Glossary: Billing Terms](/glossary/billing-terms)).
* **With dunning:** The payment failure triggers a structured recovery sequence. The system retries the payment at optimal intervals, notifies the customer, and gives them a chance to update their payment method. Many initially failed payments are recovered.

<Tip>
  Industry research indicates that up to 40% of subscription churn is involuntary -- driven by expired cards, failed payments, and declined transactions rather than a customer's decision to leave. Involuntary churn is largely preventable with effective dunning configuration.
</Tip>

### 1.2 The dunning lifecycle

```mermaid
graph TD
    A["Invoice payment attempted"] --> B{"Payment result"}
    B -->|Fails| C{"Decline type"}
    B -->|Succeeds| Z["Invoice paid ✓"]
    C -->|Hard decline| D["Dunning terminates immediately → Final failure action"]
    C -->|Soft decline| E["Dunning sequence begins"]
    E --> F["Retry 1 — e.g. Day 3"]
    F -->|Success| Z
    F -->|Fail| G["Retry 2 — e.g. Day 7 + recovery email"]
    G -->|Success| Z
    G -->|Fail| H["Additional retries per configuration..."]
    H --> I["Final retry"]
    I -->|Success| Z
    I -->|Fail| J["Final failure action: pause, cancel, or flag for review"]
```

***

## 2. Payment Retry Logic

### 2.1 Configuring the retry schedule

The dunning retry schedule defines:

* **Number of retry attempts:** How many times to retry the payment before giving up (common configurations: 3-5 retries)
* **Retry intervals:** The number of days between each retry attempt (e.g., retry on days 3, 7, 14, and 21 after the initial failure)
* **Communication triggers:** Which retries are accompanied by a customer-facing email notification

**Example retry schedule:**

| Attempt         | Days after failure | Communication                                            |
| --------------- | ------------------ | -------------------------------------------------------- |
| Initial attempt | Day 0              | None (failure only)                                      |
| Retry 1         | Day 3              | None (silent retry)                                      |
| Retry 2         | Day 7              | Email: "We had trouble collecting your payment"          |
| Retry 3         | Day 14             | Email: "Your subscription is at risk of cancellation"    |
| Retry 4 (final) | Day 21             | Email: "Final notice: please update your payment method" |
| Final failure   | Day 21             | Email: "Your subscription has been paused/cancelled"     |

### 2.2 Retry behaviour

Each retry attempt creates a payment event in the audit trail. Prolifi handles the gateway request and records the outcome. On success, the invoice transitions to "Paid" and the dunning sequence terminates. On failure, the next retry is scheduled per the configured interval.

### 2.3 Decline type handling

**Soft declines** (see [Glossary: Payments & Integration Terms](/glossary/payments-integration-terms)) are retried per the dunning schedule -- the failure is considered temporary.

**Hard declines** (see [Glossary: Payments & Integration Terms](/glossary/payments-integration-terms)) are not retried. When a hard decline is received, Prolifi terminates the dunning sequence immediately and triggers the final failure action. Retrying a hard decline will not succeed and may cause additional issues (e.g., the card issuer may flag repeated attempts on a stolen card).

<Warning>
  Prolifi classifies decline codes from the connected payment gateway as soft or hard and routes them accordingly. The classification is based on industry-standard decline code categories.
</Warning>

### 2.4 Smart retry logic

(See [Glossary: Payments & Integration Terms](/glossary/payments-integration-terms))

Smart retry enhances the base dunning schedule by optimising retry timing based on data signals. Rather than retrying at fixed intervals regardless of context, smart retry considers:

* The time of day when a particular customer's payments historically succeed
* The day of week patterns (e.g., some customers are more likely to have funds on their account on paydays)
* The specific decline reason code (some decline types clear more quickly than others)
* Bank-specific patterns

<Note>
  Smart retry requires sufficient payment history to generate meaningful signals and is most effective at scale.
</Note>

***

## 3. Dunning Communication Workflow

### 3.1 Email templates

Configure email templates for each communication point in the dunning sequence. Effective dunning emails:

* Are clear and non-judgmental in tone -- payment failures are usually accidental, not intentional
* State clearly what has happened (payment was not collected)
* Tell the customer exactly what to do (update payment method via the link provided)
* Create appropriate urgency without panic -- early emails are informational; late emails convey genuine consequence
* Include a direct link to the customer portal payment method update page

**Required email templates:**

| Template                         | Trigger                                         | Key content                                                                                         |
| -------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Payment failure notification     | First failure                                   | "We were unable to collect your payment. Please update your payment method."                        |
| Mid-dunning reminder             | Mid-sequence retry (with communication trigger) | "We tried again and are still unable to collect payment. Please update your method before \[date]." |
| Final warning                    | Last retry before final failure action          | "Your subscription will be paused/cancelled on \[date] if payment is not received."                 |
| Dunning resolved (success)       | Successful retry                                | "Your payment has been collected. Thank you."                                                       |
| Subscription paused (failure)    | Final failure, pause action                     | "Your subscription has been paused due to non-payment. Reactivate at \[link]."                      |
| Subscription cancelled (failure) | Final failure, cancel action                    | "Your subscription has been cancelled."                                                             |

### 3.2 Customer portal card update flow

When a customer receives a dunning email and clicks to update their payment method, they should be directed to a payment method update page. Options:

* **Hosted Prolifi customer portal:** Prolifi's portal includes a payment method management section. Generate a secure portal session link for the customer and embed it in dunning emails. The customer can update their card without creating a Prolifi account -- they are authenticated via the session token in the link.
* **Self-hosted payment method update:** Your application provides a card update form. After the customer enters new card details, the token is submitted to Prolifi via the payment method API. Prolifi updates the stored payment method.

<Tip>
  After a successful payment method update, configure whether Prolifi automatically retries the outstanding invoice immediately or waits for the next scheduled retry.
</Tip>

### 3.3 In-product dunning communications

In addition to email, implement in-product dunning communications for customers who are using the application but may not have seen the email:

* A banner or modal in the application notifying the customer of the payment issue
* A "fix your billing" prompt that links to the payment method update flow
* Entitlement restrictions that become progressively tighter as dunning progresses (e.g., read-only mode before full access suspension)

Implement in-product communications by subscribing to dunning webhook events and responding to them in your application's frontend logic.

***

## 5. Offline Payment Recording

For customers who are expected to pay by bank transfer or other manual means, Prolifi supports recording offline payments against outstanding invoices.

### 5.1 The offline payment path

```mermaid
graph TD
    A["Invoice generated and finalised"] --> B["Invoice sent to customer via PDF email"]
    B --> C["Customer pays by bank transfer / cheque"]
    C --> D["Finance team receives payment confirmation"]
    D --> E["Finance team records payment in Prolifi"]
    E --> F["Invoice state transitions to Paid"]
    F --> G["Reconciliation matches payment to bank settlement"]
```

### 5.2 Recording an offline payment

To record an offline payment in Prolifi:

1. Navigate to the relevant invoice
2. Select "Record offline payment"
3. Enter:
   * Payment amount (full or partial)
   * Payment date (the date payment was received, not the date recorded)
   * Payment reference (the bank reference or cheque number)
   * Payment method type (bank transfer, BACS, SWIFT, cheque, cash)
   * Notes (optional -- any relevant context)
4. Submit -- the invoice transitions to "Paid" or "Partial Paid" accordingly

### 5.3 Dunning for offline payment customers

Customers configured for manual/offline payment collection can also have dunning configured -- if an invoice reaches a defined number of days past due without being marked paid, a dunning alert is triggered. Unlike card dunning, offline dunning typically involves a notification to the Finance team rather than an automated payment retry.

Configure "offline dunning" thresholds:

* Alert if invoice is unpaid after N days
* Escalation alert if invoice is unpaid after N+M days
* Final warning before subscription action

***

## 6. Reporting on Dunning Performance

Prolifi provides dunning performance metrics to help you assess the effectiveness of your recovery configuration:

| Metric                    | Description                                                                |
| ------------------------- | -------------------------------------------------------------------------- |
| Payment recovery rate     | Percentage of initially failed payments recovered through dunning          |
| Average days to recovery  | How many days (on average) between initial failure and successful recovery |
| Recovery by retry attempt | How many recoveries happen on retry 1, 2, 3, etc.                          |
| Hard decline rate         | Percentage of failures that are hard declines (not retryable)              |
| Dunning cancellation rate | Percentage of dunning sequences that result in subscription cancellation   |
| Revenue recovered         | Total revenue recovered through the dunning sequence in a period           |

<Tip>
  Use these metrics to tune your retry schedule -- if most recoveries happen on retry 1 or 2, the additional retries may not be worth the customer experience friction. If the communication templates are generating a high click-to-update rate, the email copy is working.
</Tip>

***

## Cross-references

* [Glossary: Billing Terms](/glossary/billing-terms)
* [Glossary: Payments & Integration Terms](/glossary/payments-integration-terms)
* [Getting Started: Finance](/getting-started/finance)
* [Getting Started: Developers](/getting-started/developers)
* [Reconciliation Workflows](/reporting/reconciliation-workflows)
* [Cancellation & Retention](/payments-recovery/cancellation-retention)