Stripe Decline Codes: Complete Reference Guide

Stripe decline codes are standardized error codes returned by card networks (Visa, Mastercard, American Express) and issuing banks when a payment authorization attempt fails, providing specific reasons for the rejection and enabling merchants to communicate appropriate next steps to customers.

How Stripe Categorizes Decline Codes

Stripe groups decline codes into four primary categories based on recommended merchant action. Generic declines include codes like generic_decline and card_declined where the card issuer provides no specific reason. Insufficient funds declines use codes like insufficient_funds when the account balance cannot cover the transaction. Card-specific issues trigger codes such as expired_card, incorrect_cvc, incorrect_number, or lost_card. Fraud-related declines return codes including fraudulent, pickup_card, or stolen_card when the issuer suspects unauthorized use.

Most Common Decline Codes

According to Stripe's documentation, the most frequently encountered decline codes are:

card_declined — The most generic decline code, returned when the issuing bank refuses the charge without providing a specific reason. This accounts for an estimated 40-50% of all declines.

insufficient_funds — The cardholder's account lacks sufficient balance to complete the transaction. This is the second most common decline reason.

incorrect_cvc — The card verification code (CVC/CVV) provided does not match the issuer's records. This indicates potential manual entry errors.

expired_card — The card's expiration date has passed. Stripe automatically attempts to update expired cards through its card updater service for recurring charges.

fraudulent — The card issuer has flagged the transaction as potentially fraudulent. This may trigger when transaction patterns deviate from the cardholder's typical behavior.

do_not_honor — A generic decline issued by the bank with no specific explanation, often related to fraud prevention rules or account restrictions.

Handling Decline Codes Programmatically

Stripe returns decline codes in the API response under error.decline_code for card errors. The PaymentIntent object also includes last_payment_error.decline_code when charges fail. According to Stripe's API reference, merchants should parse these codes to customize user-facing messaging rather than displaying raw technical codes.

For subscription-based businesses, Stripe's Smart Retries system automatically re-attempts failed payments using machine learning to determine optimal retry timing, but only for certain decline codes like insufficient_funds. Codes indicating permanent failures (e.g., lost_card, stolen_card) are not retried.

Soft Declines vs. Hard Declines

Soft declines are temporary failures that may succeed if retried, including insufficient_funds, do_not_honor, or try_again_later. Industry estimates suggest soft declines represent 60-70% of all payment failures.

Hard declines indicate permanent issues requiring customer action before retry, such as expired_card, incorrect_number, fraudulent, or restricted_card. These should not be automatically retried without customer intervention.

Regional Variations

Decline code behavior varies by geography. European cards often return more specific decline reasons due to PSD2 Strong Customer Authentication requirements, while US issuers frequently use generic codes like card_declined. According to payment industry data, European transactions show approximately 15-20% higher rates of specific decline code usage compared to North American transactions.

Decline Code Analytics

Stripe's Dashboard provides decline code analytics under the Payments > Decline Insights section. Merchants can filter by specific codes to identify patterns, such as elevated incorrect_cvc rates indicating checkout UX issues, or clusters of fraudulent declines suggesting the need for stronger fraud prevention rules.

The card_velocity_exceeded decline code appears when Stripe's rate limiting detects multiple rapid authorization attempts on a single card, typically configured to prevent card testing attacks.

Best Practices for Messaging

Stripe recommends translating technical decline codes into customer-friendly language. For insufficient_funds, suggest trying a different payment method. For incorrect_cvc, prompt the customer to verify the three- or four-digit code. For generic_decline or card_declined, advise contacting the card issuer directly, as merchants cannot access the specific internal reason for these declines.