UJ-M-005: Recover from Failed Payment

Journey Overview

Preconditions

• Member has attempted a payment
• Payment was declined or failed
• Member has access to update payment method

Journey Flow

flowchart TD
    A[Payment fails] --> B[System logs failure]
    B --> C[Member notified]
    C --> D[Member accesses recovery]
    D --> E{Failure type?}
    E -->|Card issue| F[Update payment method]
    E -->|Auth required| G[Complete 3D Secure]
    E -->|Temporary| H[Auto-retry scheduled]
    F --> I[Retry payment]
    G --> I
    H --> J{Retry successful?}
    I --> J
    J -->|Yes| K[Payment successful]
    J -->|No| L[Escalate / Support]
    K --> M[Access restored]
    L --> N[Manual resolution]

Detailed Steps

1. Payment Failure Detection

   System detects payment failure via:

   • Stripe webhook: payment_intent.payment_failed
   • Stripe webhook: invoice.payment_failed
   • Real-time checkout error

   Failure recorded with:

   • Timestamp
   • Amount
   • Failure reason (Stripe error code)
   • Attempt number
   • Payment method used
2. Immediate Notification

   Member receives immediate notification:

   In-App:

   • Banner on dashboard: "Payment failed - Action required"
   • Modal if currently in checkout

   Email (sent immediately):

   Subject: Action Required: Payment Failed
   
   Hi [Name],
   
   Your payment of $[amount] for [item] was unsuccessful.
   
   Reason: [friendly error message]
   
   Please update your payment method to resolve this issue:
   [Update Payment Button]
   
   If you need assistance, contact our support team.

3. Dunning Sequence (Subscriptions)

   For subscription renewals, automated retry schedule:

   Day	Action
   0	Initial failure, email sent
   1	Auto-retry #1
   3	Auto-retry #2, email reminder
   5	Auto-retry #3
   7	Final retry, urgent email
   10	Membership suspended, final notice
   14	Membership cancelled (grace period end)

4. Member Updates Payment Method

   Member clicks recovery link:

   1. Directed to payment update page
   2. Current (failed) method shown
   3. Option to:
      • Update existing card details
      • Add new card
      • Use saved alternative card
      • Try digital wallet (Apple/Google Pay)
   4. New card validated with $0 authorization
   5. New card set as default
5. Retry Payment

   After updating payment method:

   Automatic Retry:

   • System immediately retries failed payment
   • Uses new default payment method
   • Member sees processing indicator

   Manual Retry:

   • Member clicks "Retry Payment"
   • Full checkout flow with new card
6. Success Confirmation

   On successful payment:

   • Success message displayed
   • Confirmation email sent
   • Invoice generated
   • Membership/access restored
   • Failure record marked resolved
   • Dunning sequence cancelled

Payment Failure Types

Recovery UI States

┌────────────────────────────────────────────────────────────┐
│ ⚠️ Payment Failed                                          │
│                                                            │
│ Your membership renewal payment of $99.00 failed.          │
│ Please update your payment method to maintain access.      │
│                                                            │
│ [Update Payment Method]  [Contact Support]                 │
└────────────────────────────────────────────────────────────┘

Smart Retry Logic

System implements intelligent retry:

Escalation Path

If automated recovery fails:

1. Day 7: Support team notified
2. Day 10: Member account flagged
3. Day 14: Account manager outreach (if applicable)
4. Manual options:
   • Phone payment
   • Invoice/bank transfer
   • Payment plan arrangement

Related Entities

• Payment Transaction
• User Membership
• Stripe Webhook Event

Related Journeys

• UJ-M-004
• UJ-M-003
• UJ-M-027

Acceptance Criteria

Frontend

• Payment failure banner on dashboard
• Payment update page with current card shown
• Stripe Elements for new card entry
• Error messages in plain language (not codes)
• Retry button with loading state
• Success confirmation on resolution
• Email links deep-link to recovery page

Backend

• POST /api/payments/update-method - Update payment method
• POST /api/payments/retry - Retry failed payment
• GET /api/payments/failures - Get pending failures
• Webhook: payment_intent.payment_failed
• Webhook: invoice.payment_failed
• Scheduled dunning job

Permissions

• Member can only resolve their own failures
• Support can manually resolve on behalf

Business Rules

• Maximum 4 auto-retries before stopping
• Grace period access during recovery window
• Hard declines (fraud, stolen) not retried
• Payment method update resets retry counter

Error Handling

• All failure reasons mapped to friendly messages
• Stripe error codes logged for debugging
• Support notified of repeated failures