Stripe Troubleshooting

Diagnose and resolve Stripe payment integration issues

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

Common Issues

Connection & Configuration

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

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

Payment Issues

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

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)

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

Subscription Issues

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

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

Diagnostic Endpoints

Connection Status

GET /api/admin/integrations/stripe/{organization_id}/status
Authorization: Bearer {admin_token}

Response:

{
  "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

GET /api/admin/integrations/stripe/{organization_id}/failed-transactions
Authorization: Bearer {admin_token}

Response:

{
  "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": "[e-mail]",
      "timestamp": "2025-01-15T09:15:00Z"
    }
  ],
  "total": 3,
  "page": 1
}

View Webhook Events

GET /api/admin/integrations/stripe/{organization_id}/webhooks
Authorization: Bearer {admin_token}

Response:

{
  "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

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

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