Failed payments, refunds and disputes

Failed Payments, Refunds & Disputes

Revenue recovery and financial accuracy depend on how the system handles unhappy paths: expired cards, insufficient funds, involuntary churn, voluntary cancellations, partial refunds and chargebacks.

1. Failed Renewals, Dunning & Grace Periods

When a recurring payment fails (invoice.payment_failed, BILLING.SUBSCRIPTION.PAYMENT.FAILED, mandate debit failure):

• Distinguish Hard vs. Soft Declines:
  • Soft declines (insufficient_funds, issuer_unavailable, processing_error, try_again_later): eligible for scheduled retries.
  • Hard declines (stolen_card, lost_card, invalid_account, revoked_mandate): do not retry the same instrument; immediately prompt the customer to provide a new payment method.
• Grace Period State (past_due):
  • Transition the subscription to past_due and set grace_period_ends_at according to business policy (e.g., 7–14 days).
  • Keep product entitlements active (or read-only per policy) during the grace window while surfacing a clear, actionable in-app banner and sending deduplicated dunning emails with a direct link to the Customer Billing Portal / payment-update flow.
• Recovery vs. Exhaustion:
  • When a retry or customer card update pays the open invoice (invoice.paid), clear past_due, restore active status and extend current_period_end.
  • If all dunning retries fail and the grace period expires, transition to canceled / unpaid, revoke paid entitlements cleanly, and preserve the customer's data per retention rules.

2. Voluntary Cancellation & Reactivation

• End-of-Period Cancellation (cancel_at_period_end = true):
  • Default for prepaid recurring subscriptions: stop future renewals, display the exact date when access ends ("Your Pro access remains active until Nov 30, 2026"), and allow one-click "Resume subscription" before current_period_end without re-charging.
• Immediate Cancellation:
  • Only when explicitly requested by an admin, fraud/dispute trigger, or trial cancellation policy.

3. Full & Partial Refunds

A refund is not the same as canceling a subscription:

• Decouple Refund from Subscription Status: issuing a partial goodwill refund (e.g., $10 off a $50 invoice for downtime) must not automatically cancel the customer's active subscription or revoke their entitlements!
• Full Refund Policy: clarify whether a full refund of the current period's charge also revokes current-period entitlements or clawbacks unused purchased credits (credit_lots).
• Prepaid Credit Refund Guard: before refunding a credit top-up purchase, check how many credits from that lot have already been consumed (remaining_credits < purchased_credits) and deduct/freeze the remaining lot balance atomically.
• Accounting & Invoicing Sync: every completed refund must generate an append-only ledger entry and trigger the corresponding Credit Note / Storno or Modification Invoice in the invoicing system.

4. Chargebacks & Disputes (charge.dispute.created / closed)

When a cardholder files a chargeback with their issuing bank:

1. Immediate Risk Action: record the dispute (status: 'needs_response' | 'under_review'), pause auto-renewals so you do not charge a disputed card again, and either suspend paid entitlements or flag the account for review per fraud policy.
2. Avoid Double-Refunding: once a charge is disputed, the funds are already withdrawn by the bank — never issue a separate API refund on top of an open chargeback!
3. Evidence & Resolution: expose clear audit logs (login IP/timestamps, usage records, invoice delivery, terms acceptance) for dispute evidence, and handle won (reinstate) vs. lost (permanent reversal + fee recording).