Developer cheat sheet
Stripe decline codes (2026)
A decline code tells you why the card was refused. Below are all 50 card decline codes Stripe lists: what each means, whether to retry, and a message you can show the buyer. Search a code, then copy it.
Before the table
Five kinds of decline
- 16Buyer can fix it: wrong number, CVC, date, address or PIN, or a missing 3D Secure step.
- 5Retry: a temporary error at the bank or network.
- 6Another card: no funds, a limit, or the card can’t pay this.
- 19Bank must say why: the issuer gave no reason; the buyer calls their bank.
- 4Show as generic: fraud, lost, stolen or block list. Never tell the buyer the real reason.
Card payments
Every decline code
| Code | What it means | What to do | Tell the buyer |
|---|---|---|---|
authentication_required | The payment needs authentication such as 3D Secure. | Buyer can fix it Show the authentication step again; for off-session payments, ask the customer to come back and pay. | Please confirm this payment with your bank, then try again. |
authentication_not_handled | The customer skipped required authentication, so the issuer declined again. | Buyer can fix it Run the 3D Secure or SCA flow; collect authentication on-session first. | Please confirm this payment with your bank, then try again. |
approve_with_id | The payment cannot be authorized. | Retry Retry once; if it fails again, the customer contacts their issuer. | We could not approve this payment. Please try again or contact your bank. |
call_issuer | Declined for an unknown reason. | Bank must say why The customer contacts their card issuer. | Your bank declined this payment. Please contact your bank or use another card. |
card_not_supported | The card does not support this type of purchase. | Another card The customer checks with their issuer or uses another card. | This card cannot be used for this purchase. Please use another card. |
card_velocity_exceeded | Balance, credit limit or transaction limit exceeded. Test card 4000 0000 0000 6975 | Bank must say why The customer contacts their card issuer. | Your card limit was reached. Please use another card or contact your bank. |
currency_not_supported | The card does not support this currency. | Bank must say why The customer checks with their issuer. | This card cannot pay in this currency. Please use another card. |
do_not_honor | Declined for an unknown reason. | Bank must say why The customer contacts their card issuer. | Your bank declined this payment. Please contact your bank or use another card. |
do_not_try_again deprecated | Declined for an unknown reason (deprecated). | Bank must say why The customer contacts their card issuer. | Your bank declined this payment. Please contact your bank or use another card. |
duplicate_transaction | An identical payment was submitted very recently. | Buyer can fix it Check whether the earlier payment already went through. | It looks like you just paid. Please check your email before trying again. |
expired_card | The card has expired. Test card 4000 0000 0000 0069 | Another card The customer uses another card. | This card has expired. Please use another card. |
fraudulent | Stripe suspects the payment is fraudulent. | Show as generic Show it to the customer as a generic decline. | Your bank declined this payment. Please use another card or contact your bank. |
generic_decline | Declined for an unknown reason, or blocked by Radar or Adaptive Acceptance. Test card 4000 0000 0000 0002 | Bank must say why The customer contacts their card issuer. | Your bank declined this payment. Please use another card or contact your bank. |
incorrect_address | The address is incorrect. | Buyer can fix it The customer retries with the correct address. | The billing address does not match your card. Please check it and try again. |
incorrect_cvc | The CVC is incorrect. Test card 4000 0000 0000 0127 | Buyer can fix it The customer retries with the correct CVC. | The security code is incorrect. Please check it and try again. |
incorrect_number | The card number is incorrect. Test card 4242 4242 4242 4241 | Buyer can fix it The customer retries with the correct number. | The card number is incorrect. Please check it and try again. |
incorrect_pin | The PIN is incorrect (card readers only). | Buyer can fix it The customer retries with the correct PIN. | The PIN is incorrect. Please try again. |
incorrect_zip | The postal code is incorrect. | Buyer can fix it The customer retries with the correct postal code. | The postal code does not match your card. Please check it and try again. |
insufficient_funds | Insufficient funds. Test card 4000 0000 0000 9995 | Another card The customer uses another payment method. | There are not enough funds on this card. Please use another card. |
invalid_account | The card or its account is invalid. | Bank must say why The customer checks with their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
invalid_amount | The amount is invalid or above the allowed limit. | Bank must say why If the amount is right, the customer checks with their issuer. | This amount could not be charged to your card. Please contact your bank. |
invalid_cvc | The CVC is incorrect. | Buyer can fix it The customer retries with the correct CVC. | The security code is incorrect. Please check it and try again. |
invalid_expiry_month | The expiry month is invalid. | Buyer can fix it The customer retries with the correct date. | The expiry date is incorrect. Please check it and try again. |
invalid_expiry_year | The expiry year is invalid. | Buyer can fix it The customer retries with the correct date. | The expiry date is incorrect. Please check it and try again. |
invalid_number | The card number is incorrect. | Buyer can fix it The customer retries with the correct number. | The card number is incorrect. Please check it and try again. |
invalid_pin | The PIN is incorrect. | Buyer can fix it The customer retries with the correct PIN. | The PIN is incorrect. Please try again. |
issuer_not_available | The card issuer could not be reached. | Retry Retry; if it fails again, the customer contacts their issuer. | Your bank could not be reached. Please try again in a moment. |
lost_card | The card is reported lost. Test card 4000 0000 0000 9987 | Show as generic Show it as a generic decline. | Your bank declined this payment. Please use another card or contact your bank. |
merchant_blacklist | Matches a value on your block list. | Show as generic Show it as a generic decline. | Your bank declined this payment. Please use another card or contact your bank. |
new_account_information_available | The card or its account is invalid. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
no_action_taken | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
not_permitted | The payment is not permitted. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
offline_pin_required | The card requires a PIN. | Buyer can fix it The customer inserts the card and enters a PIN. | Please insert your card and enter your PIN. |
online_or_offline_pin_required | The card requires a PIN. | Buyer can fix it Prompt for a PIN, or the customer inserts the card. | Please enter your PIN. |
pickup_card | The card cannot be used (possibly lost or stolen). | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
pin_try_exceeded | Too many PIN attempts. | Another card The customer uses another card. | Too many PIN attempts. Please use another card. |
processing_error | An error occurred processing the card. Test card 4000 0000 0000 0119 | Retry Retry; if it fails again, the customer contacts their issuer. | Something went wrong with your card. Please try again. |
reenter_transaction | The issuer could not process the payment. | Retry Retry; if it fails again, the customer contacts their issuer. | Please try the payment again. |
restricted_card | The card cannot be used (possibly lost or stolen). | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
revocation_of_all_authorizations | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
revocation_of_authorization | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
security_violation | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
service_not_allowed | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
stolen_card | The card is reported stolen. Test card 4000 0000 0000 9979 | Show as generic Show it as a generic decline. | Your bank declined this payment. Please use another card or contact your bank. |
stop_payment_order | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
testmode_decline | A test card number was used in live mode. | Another card Use a real card. | Test cards do not work for real payments. Please use your card. |
transaction_not_allowed | Declined for an unknown reason. | Bank must say why The customer contacts their issuer. | Your bank declined this payment. Please contact your bank or use another card. |
try_again_later deprecated | Declined for an unknown reason (deprecated). | Retry Retry; if it keeps failing, the customer contacts their issuer. | Please try again in a few minutes. |
withdrawal_count_limit_exceeded | Balance or credit limit exceeded. | Another card The customer uses another payment method. | Your card limit was reached. Please use another card. |
mobile_device_authentication_required | The payment needs authentication on the phone. | Buyer can fix it Ask the customer to tap their phone again. | Please confirm on your phone and tap again. |
Selling through a merchant of record
Who handles declines
With Stripe you build the checkout, so you choose the message and the retry rules for every code above. With a merchant of record, its hosted checkout shows the buyer the message and you see the failed payment in its dashboard and webhooks.
AgentaOS: you sell through our hosted checkout, so you don’t write this decline logic yourself. Try it in test mode with the test cards. Docs.
Questions
Related questions
What does do_not_honor mean on Stripe?
The card issuer declined the payment without giving a reason. The buyer has to contact their bank or use another card. Stripe lists it as declined for an unknown reason.
What is generic_decline?
The issuer declined for an unknown reason, or Stripe blocked the payment (Radar or Adaptive Acceptance). Stripe also tells you to show fraudulent, lost_card, stolen_card and merchant_blacklist to the buyer as a generic decline.
Should I retry a declined payment?
Only for temporary errors: processing_error, issuer_not_available, reenter_transaction, approve_with_id and try_again_later. For insufficient_funds or a contact-your-bank code, ask for another card instead of retrying the same one.
Why should I not tell the buyer the card is stolen?
Stripe advises showing fraudulent, lost_card, stolen_card and merchant_blacklist as a generic decline, so a person using a stolen card learns nothing from the message.
How do I test decline codes?
Use the Stripe test cards in test mode: 4000 0000 0000 0002 returns generic_decline and 4000 0000 0000 9995 returns insufficient_funds. The full list is on our Stripe test cards page.
Do merchants of record show the same codes?
A merchant of record runs the checkout for you, so its own checkout shows the buyer the message and handles retries. You see the result in its dashboard and webhooks, in its own format.
Keep reading
Related
Stripe test card numbersMerchant of Record providers comparedPut the checkout on your own siteStripe isn’t available in my country
Source: docs.stripe.com/declines/codes. Stripe is a trademark of Stripe, Inc.; AgentaOS is not affiliated with Stripe. Link to this page: https://agentaos.ai/tools/stripe-decline-codes