Failed Payment Recovery for Stripe

How this pack fits Stripe Billing

Stripe Billing uses a subscription lifecycle with automatic invoicing and built-in retry logic (Smart Retries). When a payment fails, Stripe provides a decline_code and an outcome object explaining why. The pack's classification rules map these codes to recovery actions that go beyond what Smart Retries handles alone — customer outreach, payment method updates, manual intervention, and churn prevention workflows.

Stripe objects and data this pack uses

• Invoice events: invoice.payment_failed, invoice.payment_action_required — with decline_code and failure_message
• Subscription status: active, past_due, unpaid, canceled — used to determine urgency and escalation
• Customer object: email, name, default payment method, and metadata for segmentation
• Payment Intent: decline_code (e.g. insufficient_funds, card_declined, expired_card), last_payment_error
• Billing portal: used to direct customers to update payment methods self-service
• Webhook payloads: the full event object including invoice, subscription, and customer links

Workflow steps

1. 1

   Webhook receipt and event parsing

   Your application receives a Stripe webhook (invoice.payment_failed), verifies the signature, and extracts the decline_code, invoice, subscription, and customer data.

2. 2

   Failure classification

   The pack's classification rules map the decline_code and subscription status to a recovery category. The event is logged with the classification result.

3. 3

   Smart Retries monitoring or immediate action

   For card-retryable codes, the workflow monitors Stripe Smart Retries outcomes. For card-update-required or authentication-required codes, immediate customer outreach begins.

4. 4

   Customer communication and self-service

   Templated emails direct the customer to the Stripe Billing portal to update their payment method. The tone and urgency escalate with each failed retry.

5. 5

   Dunning escalation and resolution tracking

   If the subscription moves to past_due or unpaid, the dunning workflow escalates outreach. Each failure is tracked through to resolution (successful payment, method update, cancellation, or write-off).

Decision and escalation logic for Stripe

• The pack's classification logic maps the decline_code to a recovery category: card-retryable (insufficient_funds), card-update-required (expired_card), authentication-required (authentication_required), or non-recoverable (stolen_card)
• Card-retryable failures are left to Stripe Smart Retries initially, with the pack monitoring retry outcomes and escalating if retries are exhausted
• Card-update-required failures trigger a customer email with a Stripe Billing portal link for self-service payment method update
• If Stripe exhausts its retry attempts and the subscription moves to past_due, the pack's dunning workflow begins with escalating outreach
• High-value subscriptions or enterprise accounts are escalated to a senior team member for personal outreach

Implementation considerations

• Review your existing Stripe Smart Retries settings before deploying the pack. The pack's retry monitoring complements Smart Retries rather than replacing them.
• Use Stripe's test mode and test card numbers (e.g. 4000000000000341 for attach-required) to verify each classification path before going live.
• Configure your Stripe Billing portal to allow customers to update payment methods and view invoice history. The pack directs customers there for self-service recovery.
• If you use Stripe with a billing platform (e.g. Chargebee, Recurly), ensure the pack webhook handler does not conflict with the platform connector.

Frequently asked questions

Related pages