Stripe Payment Failure Codes Explained: What Each One Means and How to Fix It

Understanding Stripe Decline Codes

When a payment fails on Stripe, you don't just get "payment failed" — you get a specific decline code that tells you why it failed. Understanding these codes is critical because:

• 🎯 Different codes require different strategies — retrying an expired card won't work, but retrying insufficient funds might
• ⏱️ Timing matters — some failures should be retried immediately, others need days
• 📧 Customer communication varies — your dunning email should match the decline reason

How Stripe Decline Codes Work

When Stripe attempts to charge a card, it communicates with the customer's bank (the issuing bank). The bank either approves or declines the charge, sending back a decline code that explains why.

Stripe surfaces these codes in:

• ✅ Your Stripe Dashboard (Payments → Failed)
• ✅ Webhook events (charge.failed)
• ✅ API responses (in the decline_code field)

Each code falls into one of three categories:

The Most Common Stripe Decline Codes (And What to Do About Each)

1. card_declined — Generic Decline

What it means: The bank declined the charge, but didn't provide a specific reason. This is the most common decline code.

Why it happens:

• 💰 Insufficient funds (but the bank didn't specify this)
• 🚨 Fraud detection triggered by unusual activity
• 🔒 Daily spending limit reached
• 🌍 International transaction blocked

Optimal retry strategy:

What to tell the customer: "Your bank declined the charge. This can happen for several reasons — try contacting your bank or using a different payment method."

2. insufficient_funds — Not Enough Money

What it means: The cardholder doesn't have enough funds available to cover the charge.

Why it happens:

• 💸 Low account balance at billing time
• 📅 Billing date hit before payday
• 💳 Credit limit reached

Optimal retry strategy:

What to tell the customer: "We had trouble processing your payment. We'll automatically retry in a few days, or you can update your payment method now."

3. expired_card — Card Expired

What it means: The card on file has passed its expiration date.

Why it happens:

• 📅 Customer didn't update their card info after receiving a new one
• 💳 20-40% of cards expire annually — this is extremely common

Optimal retry strategy:

What to tell the customer: "Your card ending in [last 4] expired on [date]. Update your payment method to keep your subscription active."

Prevention: Enable Stripe's Card Account Updater to automatically refresh expired cards (reduces expired card failures by 30-40%).

4. lost_card / stolen_card — Card Reported Lost or Stolen

What it means: The cardholder reported the card as lost or stolen to their bank.

Why it happens:

• 🚨 Card was genuinely lost or stolen
• 💳 Customer got a new card and deactivated the old one

Optimal retry strategy:

What to tell the customer: "We can't process payments with the card ending in [last 4]. Please add your new card to keep your account active."

5. do_not_honor — Bank Refused (No Specific Reason)

What it means: The bank declined the transaction but didn't provide a specific reason. Often related to suspected fraud.

Why it happens:

• 🚨 Fraud detection system flagged the transaction
• 🌍 Unusual purchase pattern (e.g., international charge)
• 🔒 Bank's internal risk rules

Optimal retry strategy:

What to tell the customer: "Your bank declined the charge for security reasons. Please contact your bank to authorize the payment, or use a different card."

6. incorrect_cvc — Wrong CVV Code

What it means: The CVV (card security code) provided doesn't match the card.

Why it happens:

• 🔢 Customer typo when entering CVV
• 💳 Using a saved card with incorrect CVV on file

Optimal retry strategy:

What to tell the customer: "We couldn't verify your card's security code (CVV). Please re-enter your card details."

7. processing_error — Temporary Technical Issue

What it means: A temporary error occurred while processing the payment (usually on Stripe's or the bank's side).

Why it happens:

• ⚡ Network timeout or connectivity issue
• 🏦 Bank's payment system temporarily down
• 🔧 Rare Stripe infrastructure issue

Optimal retry strategy:

What to tell the customer: "We had a temporary technical issue processing your payment. We'll retry automatically — no action needed."

8. incorrect_number — Invalid Card Number

What it means: The card number provided is invalid or doesn't exist.

Why it happens:

• 🔢 Typo when entering card number
• 💳 Fake or test card number used

Optimal retry strategy:

What to tell the customer: "The card number you provided appears to be incorrect. Please double-check and re-enter your card details."

9. card_velocity_exceeded — Too Many Charges Too Fast

What it means: The card has been used too many times in a short period, triggering velocity limits.

Why it happens:

• 🚨 Anti-fraud mechanism (too many charges in 24h)
• 🔁 Multiple retry attempts in quick succession

Optimal retry strategy:

What to tell the customer: "Your bank flagged this charge due to multiple recent transactions. We'll retry in 24 hours, or you can use a different payment method."

10. fraudulent / card_not_supported — Fraud Block

What it means: Stripe's fraud detection system (Stripe Radar) blocked the charge as potentially fraudulent.

Why it happens:

• 🚨 High-risk transaction pattern
• 🌍 Mismatch between card country and IP address
• 💳 Card linked to previous fraudulent activity

Optimal retry strategy:

What to tell the customer: "This transaction was flagged for security reasons. Please contact us to verify your identity or use a different payment method."

Quick Reference: Stripe Decline Codes Cheat Sheet

How to Implement Smart Retry Logic Based on Decline Codes

Now that you know what each code means, here's how to build (or choose) a retry system that adapts to decline codes:

Option 1: Build Custom Retry Logic (Developer Route)

Use Stripe webhooks to listen for charge.failed events:

// Example webhook handler (Node.js)
stripe.webhooks.constructEvent(request.body, sig, webhookSecret);

if (event.type === 'charge.failed') {
  const charge = event.data.object;
  const declineCode = charge.outcome?.decline_code;
  
  // Route to appropriate retry strategy
  if (declineCode === 'insufficient_funds') {
    scheduleRetry(charge.id, { days: 2 });
  } else if (declineCode === 'expired_card') {
    sendDunningEmail(customer, 'expired_card');
  } else if (declineCode === 'processing_error') {
    scheduleRetry(charge.id, { hours: 1 });
  }
  // ... handle other codes
}

Option 2: Use a Payment Recovery Tool (No-Code Route)

Tools like Revive automatically handle decline-code-specific retry logic without any code:

• ✅ Reads Stripe decline codes automatically
• ✅ Schedules retries based on best practices for each code
• ✅ Sends personalized dunning emails matching the decline reason
• ✅ Shows recovery metrics by decline code type

Advanced: Less Common Decline Codes

Here are a few more decline codes you might encounter:

• generic_decline — Similar to card_declined, no specific reason given
• call_issuer — Bank wants cardholder to call them (often fraud-related)
• pickup_card — Bank wants to physically retrieve the card (rare, serious fraud indicator)
• restricted_card — Card is restricted by the bank (e.g., region-locked)
• currency_not_supported — Card doesn't support the charge currency
• duplicate_transaction — Identical transaction attempted twice in short window

For a complete list, see Stripe's official decline codes documentation.

Best Practices for Handling Stripe Declines

1. 1. Log every decline code — Track which codes you see most often to identify patterns (e.g., if 50% are expired cards, prioritize Card Account Updater)
2. 2. Don't retry indiscriminately — Retrying expired cards wastes resources and annoys banks
3. 3. Customize dunning emails per decline reason — An email about an expired card should look different than one about insufficient funds
4. 4. Monitor retry success rates by code — If insufficient_funds retries aren't working, adjust timing
5. 5. Offer backup payment methods — When a card fails repeatedly, let customers add ACH, PayPal, or other options

Key Takeaways

• 💡 Not all payment failures are equal — each Stripe decline code requires a different strategy
• 💡 Expired cards, lost cards, and incorrect CVVs should NOT be retried — email the customer immediately
• 💡 Insufficient funds failures recover best when retried around payday (1st, 15th, end of month)
• 💡 Processing errors usually resolve on their own — retry quickly (1h → 6h → 24h)
• 💡 Generic declines (card_declined) benefit from spaced-out retries (4h → 1d → 3d → 7d)
• 💡 Track which decline codes are most common to optimize your prevention and recovery strategies

The bottom line: Smart retry logic based on decline codes can increase your payment recovery rate by 40-60%. Stop treating all failed payments the same — adapt your strategy to the specific reason each one failed.