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:
- Verify API keys are correctly configured
- Check if using test vs live keys appropriately
- Confirm keys haven't been rotated/revoked
- Verify restricted key has required permissions
Webhook failures
Symptoms:
- Payment status not updating
- Subscriptions not activating after payment
Resolution:
- Check webhook endpoint is accessible
- Verify webhook signing secret is correct
- Review webhook logs in Stripe dashboard
- Check for failed webhook deliveries
Payment Issues
Payment declined
Common causes:
- Insufficient funds
- Card expired
- Fraud detection triggered
- 3D Secure authentication failed
Troubleshooting:
- Check decline code in transaction record
- Review Stripe Radar rules if fraud-related
- Verify 3D Secure is properly configured
- Check if card requires additional authentication
Subscription not activating
Common causes:
- Webhook not received
- Payment intent not confirmed
- Subscription status not syncing
Troubleshooting:
- Check Stripe dashboard for subscription status
- Review webhook delivery logs
- Verify webhook handler processed event
- 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:
- Verify original charge status and amount
- Check existing refunds on charge
- Review Stripe account balance
- Check refund policy timeframes
Subscription Issues
Billing not occurring
Common causes:
- Subscription paused or cancelled
- Payment method expired
- Billing anchor date misconfigured
Resolution:
- Check subscription status in Stripe
- Verify default payment method is valid
- Review billing cycle anchor settings
- Check for past_due status
Proration issues
Common causes:
- Proration behavior misconfigured
- Plan change timing
- Credit balance not applied
Troubleshooting:
- Review proration settings on subscription
- Check upcoming invoice preview
- 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": "user@example.com",
"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:
- Collect organization ID, Stripe account ID, payment intent IDs
- Check Stripe Status page for incidents
- Review Stripe dashboard logs directly if needed
- Contact Stripe support for account-level issues