Stripe Decline Codes Explained

Stripe decline codes are standardized error identifiers returned by card networks and issuing banks when a payment cannot be processed, categorized into soft declines (temporary issues where automatic retries may succeed) and hard declines (permanent blocks requiring customer action before any retry).

Soft Decline Codes: Retry-Safe Scenarios

Soft declines represent temporary payment failures where the underlying payment method remains valid and automatic retry logic may result in successful authorization. These codes account for approximately 20–30% of all declined transactions according to payment industry benchmarks.

Common soft decline codes include:

• generic_decline – The most common soft decline, often issued when banks perform risk checks or experience temporary processing issues
• issuer_not_available – The card issuer's authorization system is temporarily offline or unreachable
• processing_error – A technical error occurred during transaction processing at the network or issuer level
• try_again_later – Explicit instruction from the issuer that the transaction may succeed if retried after a delay

For soft declines, Stripe's Smart Retries feature automatically reattempts authorization using machine learning to identify optimal retry timing, typically within 24–72 hours. Manual retry attempts should implement exponential backoff (waiting progressively longer between attempts) to avoid triggering fraud detection systems.

Hard Decline Codes: Customer Action Required

Hard declines indicate permanent authorization failures that will consistently fail regardless of retry timing or frequency. These represent 70–80% of payment declines and require the customer to resolve the underlying issue before any successful charge can occur.

Critical hard decline codes include:

• insufficient_funds – The account lacks available balance to cover the transaction amount
• card_declined – Generic permanent decline, often due to issuer risk rules or account restrictions
• expired_card – The payment method has passed its expiration date
• incorrect_cvc / incorrect_number / incorrect_zip – Card details provided do not match issuer records
• lost_card / stolen_card – The card has been reported compromised and is permanently blocked
• do_not_honor / do_not_try_again – Explicit issuer instruction to cease authorization attempts
• fraudulent – Stripe's Radar or the issuer has flagged the transaction as fraudulent
• card_not_supported – The card type is not accepted (e.g., prepaid cards when prohibited)
• currency_not_supported – The card cannot process transactions in the requested currency

Stripe's decline_code API Parameter

Stripe returns decline information in the last_payment_error.decline_code field of failed PaymentIntent or Charge objects. This code originates from the card network or issuing bank and follows standardized industry codes defined by Visa, Mastercard, American Express, and Discover.

Example API response excerpt:

"last_payment_error": {
  "code": "card_declined",
  "decline_code": "insufficient_funds",
  "message": "Your card has insufficient funds."
}

The decline_code provides granular failure reasons, while the code field categorizes the error type at Stripe's API level.

Retry Strategy Best Practices

For soft declines:

• Enable Stripe Smart Retries for automatic optimization
• If implementing manual retries, wait at least 24 hours before first retry
• Limit retry attempts to 2–3 maximum to avoid issuer penalties
• Monitor retry success rates by decline code to refine logic

For hard declines:

• Never retry without customer intervention
• Prompt customers to update payment details or contact their bank
• Use Stripe's decline messages (available in last_payment_error.message) to communicate specific action needed
• For insufficient_funds, consider offering alternate payment methods or reduced payment amounts

Decline Code Distribution

According to payment industry data, the most frequent decline codes are:

1. generic_decline (18–25% of declines)
2. insufficient_funds (15–20%)
3. card_declined (15–18%)
4. do_not_honor (8–12%)
5. expired_card (5–8%)

Decline patterns vary significantly by industry vertical, geographic market, and average transaction value. Subscription businesses typically see higher rates of insufficient_funds and expired_card, while one-time purchases generate more generic_decline and fraud-related codes.

Regulatory and Network Compliance

Card networks impose strict rules on retry behavior. Visa and Mastercard guidelines prohibit retrying hard decline codes without explicit customer action, and excessive retry attempts can result in merchant penalties or processing privilege revocation. Stripe's retry logic is designed to comply with these network rules automatically when Smart Retries is enabled.