UJ-M-005: Recover from Failed Payment

Member resolves a failed payment to restore or maintain membership access

Journey Overview

Attribute	Value
Journey ID	UJ-M-005
Actor	Member with failed payment
Goal	Resolve payment issue and restore/maintain membership
Trigger	Payment fails for renewal, event, or other purchase
Outcome	Payment successful, access restored

Preconditions

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

Journey Flow

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

Failure Type	Common Causes	System Response
Card Declined	Insufficient funds, card limit	Retry with different card
Card Expired	Past expiry date	Update card details
Authentication Failed	3D Secure rejected	Retry authentication
Network Error	Temporary connectivity	Auto-retry
Fraud Block	Suspicious activity	Contact bank
Invalid Card	Incorrect details	Re-enter card

Recovery UI States

Dashboard Banner

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

Payment Update Form

• Failed card shown (last 4 digits, expired indicator)
• Stripe Elements form for new card
• Saved alternative cards if available
• Clear error message explaining failure
• “Update and Retry” button

Smart Retry Logic

System implements intelligent retry:

Factor	Optimization
Time of day	Retry at different times
Day of week	Avoid weekends for business cards
Card type	Different retry intervals
Previous success	Prioritize previously working methods
Failure reason	Skip retries for hard declines

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