Dunning & Payment Recovery

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

---

1. What Dunning Is and Why It Matters

Dunning (see 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).
• 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.

1.2 The dunning lifecycle

---

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:

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) are retried per the dunning schedule — the failure is considered temporary.

Hard declines (see 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).

2.4 Smart retry logic

(See 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

---

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:

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.

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

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:

---

Cross-references

• Glossary: Billing Terms
• Glossary: Payments & Integration Terms
• Getting Started: Finance
• Getting Started: Developers
• Reconciliation Workflows
• Cancellation & Retention