Decline codes
Stripe decline codes: what each one means and how to fix it
Checked
Stripe decline codes tell you why a card payment failed on Stripe. Some come from the card's bank, such as insufficient_funds or expired_card; a few come from Stripe itself, such as fraudulent or merchant_blacklist. Stripe returns them as the decline_code on a card_declined error. Each page below explains one code, says whether a retry can work under card network rules, and shows what PlatformDTC checkout and subscription renewals do with it.
| Code | Meaning |
|---|---|
| authentication_required | The bank wants the cardholder to verify the payment, usually with 3D Secure. |
| authentication_not_handled | Verification was required, the shopper skipped it, and the bank declined again. |
| approve_with_id | The bank could not authorize the payment as sent; one more try may work. |
| call_issuer | The bank declined without a reason and wants the cardholder to contact it. |
| card_not_supported | The card can't be used for this kind of purchase. |
| card_velocity_exceeded | The card's balance, credit limit or amount limit has been reached. |
| currency_not_supported | The card can't be charged in the currency of the payment. |
| do_not_honor | The bank declined the card without saying why. |
| do_not_try_again | Deprecated code: declined for an unknown reason; don't charge this card again. |
| duplicate_transaction | An identical payment on the same card was submitted moments ago. |
| expired_card | The card is past its expiry date. |
| fraudulent | Stripe's fraud checks suspected the payment was fraudulent and blocked it. |
| generic_decline | Declined for an unknown reason, or blocked by Stripe Radar or Adaptive Acceptance. |
| incorrect_address | The billing address entered doesn't match the bank's records. |
| incorrect_cvc | The card's security code (CVC) is wrong. |
| incorrect_number | The card number entered is wrong. |
| incorrect_pin | The PIN entered on a card reader is wrong. |
| incorrect_zip | The billing postal code doesn't match the bank's records. |
| insufficient_funds | The card doesn't have enough money or credit for this payment. |
| invalid_account | The card or the account behind it is no longer valid. |
| invalid_amount | The payment amount is invalid or above what the card allows. |
| invalid_cvc | The card's security code (CVC) is incorrect. |
| invalid_expiry_month | The card's expiry month is invalid. |
| invalid_expiry_year | The card's expiry year is invalid. |
| invalid_number | The card number is incorrect. |
| invalid_pin | The PIN entered is incorrect. |
| issuer_not_available | The card's bank could not be reached, so the payment was never authorized. |
| lost_card | The card has been reported lost. It can't be used; the shopper needs another card. |
| merchant_blacklist | The payment matched an entry on the store's own Stripe block list. |
| new_account_information_available | The card or its account is invalid; the bank may hold newer details for it. |
| no_action_taken | The card was declined for a reason the bank did not share. |
| not_permitted | The bank says this payment is not permitted on this card. |
| offline_pin_required | In-person only: the card needs to be inserted and a PIN entered. |
| online_or_offline_pin_required | In-person only: the card needs a PIN, by Online PIN or chip and PIN. |
| pickup_card | The card can't be used for this payment; it may have been reported lost or stolen. |
| pin_try_exceeded | Too many wrong PIN attempts; the customer must use another card or method. |
| processing_error | An error occurred while processing the card. Usually temporary. |
| reenter_transaction | The bank couldn't process the payment for an unknown reason; try it again. |
| restricted_card | The card can't be used for this payment; it may have been reported lost or stolen. |
| revocation_of_all_authorizations | The bank declined; typically the cardholder has stopped all future payments. |
| revocation_of_authorization | The bank declined; typically the cardholder revoked payments to this store. |
| security_violation | The bank declined for a reason it did not share; often a security rule. |
| service_not_allowed | The card was declined for a reason the bank did not give. |
| stolen_card | The card has been reported stolen. It can't be used again. |
| stop_payment_order | The bank declined; the code's name points to a stop-payment order on the card. |
| testmode_decline | A Stripe test card number was used in a real payment. |
| transaction_not_allowed | The bank declined; the card does not allow this type of transaction. |
| try_again_later | Deprecated code: the bank declined for an unknown reason; try again later. |
| withdrawal_count_limit_exceeded | The customer has gone over the balance or credit limit available on the card. |
| mobile_device_authentication_required | The payment needs authentication; the customer should tap their phone again. |
| card_declined | Stripe's error code for any declined card; the decline_code says why. |
| payment_intent_authentication_failure | The card failed the bank's authentication check (such as 3-D Secure). |
Which Stripe decline codes can be retried
Stripe sorts many declines as generic, so the exact reason is often unclear. As a rule of thumb, funds, limit and temporary codes can clear later; wrong card details need the shopper to re-enter them; lost, stolen, closed, restricted and expired cards need a different card.
Stripe also returns an advice code with some declines: do_not_try_again means do not use the card again for that payment, try_again_later means a retry is allowed, and confirm_card_data means some card details are wrong. Stripe recommends at most eight retries for a charge that permits retries.
On the default fixed schedule (retries 1, 3, 5 and 7 days apart), declines in the last two groups also stop at the first failure: the card is not retried, the subscription is held past due and the customer gets the update-card or confirm-payment email. Only the other groups are retried on that schedule.
| Group | Example codes | What happens |
|---|---|---|
| Low funds | insufficient_funds | Retried on the customer's likely payday, or 2, 5, 8, 13 and 18 days after the first decline: up to 6 attempts (7 on PayPal, 2 on a prepaid card) |
| Temporary | processing_error, issuer_not_available, try_again_later, card_velocity_exceeded, card_decline_rate_limit_exceeded | Retried 2, 5 and 8 days after the first decline: up to 4 attempts |
| No reason given | do_not_honor, generic_decline, call_issuer, approve_with_id, no_action_taken, duplicate_transaction | One retry 48 to 72 hours later, then the customer is asked for a new card |
| Bank confirmation needed | authentication_required, authentication_not_handled, mobile_device_authentication_required | No blind retry; the customer is asked to confirm the payment with their bank |
| Card can't be used | lost_card, stolen_card, expired_card, incorrect_number, incorrect_zip, restricted_card, pin_try_exceeded, do_not_try_again | Never retried; the customer gets a one-click link to update the card |
What PlatformDTC does at checkout
The shopper sees Stripe's decline message, plus a plain hint for the common codes, such as "Your card has insufficient funds. Try another card." and an option to try another card straight away. For lost_card, stolen_card, pickup_card, fraudulent and merchant_blacklist the hint is always the generic "Your card was declined. Try another card or contact your bank.", so the shopper is never told a card was reported lost or stolen or flagged.
If the store has chosen PayPal card payments as its backup, a bank refusal with no lasting reason, such as do_not_honor or processing_error, can be tried again through PayPal, where the shopper enters the card again. Funds, 3-D Secure, wrong-details, dead-card and fraud declines are never moved to the backup.
Frequently asked questions
- Where do I find the decline code for a Stripe payment?
- In the Stripe Dashboard, open the failed payment: the decline reason is shown with a short suggested fix. In the API it is the decline_code on the PaymentIntent's last_payment_error, and the charge's outcome also carries the reason, an advice code and, when the network sent one, the raw network decline code.
- What is the most common Stripe decline code?
- Stripe says card banks categorize most declines as generic (generic_decline), which leaves the exact reason unclear. If the card information is correct, Stripe advises asking the customer to contact their card bank to learn why the payment was declined.
- How many times can I retry a declined Stripe payment?
- Stripe recommends a maximum of eight retries for charges that permit retries, and warns that extra retries can look like fraud to card banks. Visa allows up to 20 attempts in 30 days on retryable declines and none at all after a Category 1 decline such as a lost or stolen card.
- Should I tell the shopper the exact decline reason?
- For most codes, yes: a plain reason like an expired card or a wrong security code helps them fix it. For fraudulent, lost_card, stolen_card and merchant_blacklist, Stripe says not to give details and to show the decline the same way as generic_decline.
Sources
- Stripe decline codes — Stripe
- Card declines — Stripe
- Error codes — Stripe
- Visa Core Rules and Visa Product and Service Rules (24 October 2026), Table 7-2 — Visa