> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
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

<Steps>
  <Step title="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
  </Step>

  <Step title="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.
    ```
  </Step>

  <Step title="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) |
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="Success Confirmation">
    On successful payment:

    * Success message displayed
    * Confirmation email sent
    * Invoice generated
    * Membership/access restored
    * Failure record marked resolved
    * Dunning sequence cancelled
  </Step>
</Steps>

## 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

<Tabs>
  <Tab title="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]                 │
    └────────────────────────────────────────────────────────────┘
    ```
  </Tab>

  <Tab title="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
  </Tab>
</Tabs>

## 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`](/entities/integration/payment-transaction)
* [`User Membership`](/entities/core/user-membership)
* [`Stripe Webhook Event`](/entities/integration/stripe-webhook-event)

## Related Journeys

* [UJ-M-004](/member/journeys/renew-membership)
* [UJ-M-003](/member/journeys/choose-membership-plan)
* [UJ-M-027](/member/journeys/submit-support-ticket)

## 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