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

# Stripe Troubleshooting

> Diagnose and resolve Stripe payment integration issues

Platform administrators can diagnose and assist with Stripe payment integration issues.

## Common Issues

### Connection & Configuration

<AccordionGroup>
  <Accordion title="API key issues">
    **Symptoms:**

    * All payment operations failing
    * "Invalid API Key" errors

    **Resolution:**

    1. Verify API keys are correctly configured
    2. Check if using test vs live keys appropriately
    3. Confirm keys haven't been rotated/revoked
    4. Verify restricted key has required permissions
  </Accordion>

  <Accordion title="Webhook failures">
    **Symptoms:**

    * Payment status not updating
    * Subscriptions not activating after payment

    **Resolution:**

    1. Check webhook endpoint is accessible
    2. Verify webhook signing secret is correct
    3. Review webhook logs in Stripe dashboard
    4. Check for failed webhook deliveries
  </Accordion>
</AccordionGroup>

### Payment Issues

<AccordionGroup>
  <Accordion title="Payment declined">
    **Common causes:**

    * Insufficient funds
    * Card expired
    * Fraud detection triggered
    * 3D Secure authentication failed

    **Troubleshooting:**

    1. Check decline code in transaction record
    2. Review Stripe Radar rules if fraud-related
    3. Verify 3D Secure is properly configured
    4. Check if card requires additional authentication
  </Accordion>

  <Accordion title="Subscription not activating">
    **Common causes:**

    * Webhook not received
    * Payment intent not confirmed
    * Subscription status not syncing

    **Troubleshooting:**

    1. Check Stripe dashboard for subscription status
    2. Review webhook delivery logs
    3. Verify webhook handler processed event
    4. Check for idempotency issues (duplicate events)
  </Accordion>

  <Accordion title="Refund failures">
    **Common causes:**

    * Refund exceeds charge amount
    * Charge already refunded
    * Charge too old (beyond refund window)
    * Insufficient balance

    **Troubleshooting:**

    1. Verify original charge status and amount
    2. Check existing refunds on charge
    3. Review Stripe account balance
    4. Check refund policy timeframes
  </Accordion>
</AccordionGroup>

### Subscription Issues

<AccordionGroup>
  <Accordion title="Billing not occurring">
    **Common causes:**

    * Subscription paused or cancelled
    * Payment method expired
    * Billing anchor date misconfigured

    **Resolution:**

    1. Check subscription status in Stripe
    2. Verify default payment method is valid
    3. Review billing cycle anchor settings
    4. Check for past\_due status
  </Accordion>

  <Accordion title="Proration issues">
    **Common causes:**

    * Proration behavior misconfigured
    * Plan change timing
    * Credit balance not applied

    **Troubleshooting:**

    1. Review proration settings on subscription
    2. Check upcoming invoice preview
    3. Verify credit balance application
  </Accordion>
</AccordionGroup>

## Diagnostic Endpoints

### Connection Status

```bash theme={null}
GET /api/admin/integrations/stripe/{organization_id}/status
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "connected": true,
  "mode": "live",
  "account_id": "acct_xxx",
  "webhook_status": "healthy",
  "last_webhook_received": "2025-01-15T10:30:00Z",
  "webhook_failures_24h": 0,
  "pending_webhooks": 0
}
```

### View Failed Transactions

```bash theme={null}
GET /api/admin/integrations/stripe/{organization_id}/failed-transactions
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "transactions": [
    {
      "id": "txn-uuid",
      "stripe_payment_intent": "pi_xxx",
      "amount": 9900,
      "currency": "aud",
      "status": "failed",
      "decline_code": "insufficient_funds",
      "decline_message": "Your card has insufficient funds.",
      "member_id": "member-uuid",
      "member_email": "user@example.com",
      "timestamp": "2025-01-15T09:15:00Z"
    }
  ],
  "total": 3,
  "page": 1
}
```

### View Webhook Events

```bash theme={null}
GET /api/admin/integrations/stripe/{organization_id}/webhooks
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "events": [
    {
      "id": "evt_xxx",
      "type": "payment_intent.succeeded",
      "status": "processed",
      "received_at": "2025-01-15T10:30:00Z",
      "processed_at": "2025-01-15T10:30:01Z"
    },
    {
      "id": "evt_yyy",
      "type": "customer.subscription.updated",
      "status": "failed",
      "received_at": "2025-01-15T09:15:00Z",
      "error": "Subscription not found in system",
      "retry_count": 3
    }
  ]
}
```

### Retry Webhook

```bash theme={null}
POST /api/admin/integrations/stripe/{organization_id}/webhooks/retry
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "event_ids": ["evt_xxx", "evt_yyy"]
}
```

### Sync Subscription Status

```bash theme={null}
POST /api/admin/integrations/stripe/{organization_id}/sync-subscription
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "member_id": "member-uuid"
}
```

## Escalation

For complex Stripe issues:

1. Collect organization ID, Stripe account ID, payment intent IDs
2. Check Stripe Status page for incidents
3. Review Stripe dashboard logs directly if needed
4. Contact Stripe support for account-level issues