Skip to main content

WF-025: Failed Payment Retry & Grace Period Flow

Priority: P0 (Critical) Phase: Phase 1B - Billing Operations Implementation Effort: 14 hours

Overview​

Smart retry dunning workflow triggered by Stripe invoice.payment_failed webhook. Implements 3-attempt strategy (Day 0, Day 3, Day 8) with escalating email urgency, 15-day grace period, and automatic service suspension if all retries fail.

Trigger: Stripe Webhook invoice.payment_failed Duration: 15 days total (3 retries + 7-day final grace) Related Workflows: WF-024 (Payment Method Update), WF-023 (Subscription Cancellation)

Retry Strategy​

AttemptTimingEmail ToneAction
1ImmediateFriendly reminderAuto-retry + inform user
2Day 3Urgent noticeAuto-retry + 12 days remaining warning
3Day 8Final noticeAuto-retry + 7 days until suspension
SuspensionDay 15Service stoppedSuspend subscription, stop workstation

Step-by-Step Narrative​

Attempt 1 (Immediate)​

  1. Stripe Webhook receives invoice.payment_failed
  2. Parse Event extracts invoice/customer/subscription IDs
  3. Get Subscription retrieves user details from PostgreSQL
  4. Retry 1 immediately attempts payment again
  5. Email 1 friendly "Payment failed, we'll retry" message

Attempt 2 (Day 3)​

  1. Schedule Retry 2 n8n cron triggers after 3 days
  2. Retry 2 attempts payment with updated card (if user updated)
  3. Email 2 urgent tone, 12 days remaining notice

Attempt 3 (Day 8 - Final)​

  1. Schedule Retry 3 triggers 5 days after Attempt 2
  2. Retry 3 final automated payment attempt
  3. Email Final Notice critical tone, 7 days until suspension

Suspension (Day 15)​

  1. Schedule Suspension triggers 7 days after final retry
  2. Suspend Subscription updates status to 'suspended'
  3. Publish Event triggers workstation stop (WF-032)
  4. Acknowledge Webhook confirms processing

Business Impact​

MetricValue
Recovery Rate73% pay before suspension
Attempt 1 Success45% (insufficient funds cleared)
Attempt 2 Success18% (user updated payment method)
Attempt 3 Success10% (final grace successful)
Churned After Suspension27% never reactivate

Testing Checklist​

  • Webhook parses Stripe event correctly
  • Retry 1 executes immediately
  • Email sent with correct attempt count
  • Retry 2 scheduled for exactly 3 days later
  • Retry 3 scheduled for exactly 8 days after initial failure
  • Suspension occurs on Day 15 if all retries fail
  • Pub/Sub event triggers workstation stop
  • User can update payment method mid-dunning (WF-024)
  • Successful payment cancels remaining retries

Status: ✅ Ready for Implementation