When a payment fails, the Payment object carries a machine-readable
decline_code and a human-readable decline_message. The same codes appear
on failed refunds and in card_error responses.
Use decline_code to decide what to do next; use decline_message (or your
own localized copy) to tell the customer.
Retry guidance legend
| Action | Meaning |
|---|
| Retry | Transient — the same card may succeed in a new attempt after a short delay. |
| New method | Ask the customer for another card or payment method. |
| Fix entry | The customer likely mistyped a field — let them correct it and try again. |
| Check the request | Your integration sent something invalid — fix the request on your side. |
A payment that reached FAILED is final — statuses never move backward.
“Retrying” always means creating a new payment with a new
Idempotency-Key, never re-submitting the failed one.
Card declines
decline_code | Default message | Suggested action |
|---|
generic_decline | The card was declined for an unknown reason. | New method |
do_not_honor | The card was declined. Contact your card issuer for details. | New method |
issuer_declined | The card was declined by the issuing bank. | New method |
insufficient_funds | The card has insufficient funds to complete the purchase. | New method |
invalid_number | The card number is not a valid credit card number. | Fix entry / new method |
invalid_expiry | The card expiration date is invalid. | Fix entry / new method |
expired_card | The card has expired. | New method |
invalid_amount | The transaction amount is invalid. | Check the request |
invalid_currency | The currency is not supported for this card. | Check the request |
not_permitted | This transaction type is not permitted for the card. | New method |
cardholder_limit | The cardholder has exceeded their transaction limit. | New method |
card_velocity_exceeded | The card has exceeded its withdrawal limit. | New method |
lost_card | The card has been reported lost. | New method |
stolen_card | The card has been reported stolen. | New method |
suspect_fraud | The transaction was flagged as potentially fraudulent. | New method |
fraud_filter | The payment was blocked by fraud prevention rules. | New method |
payment_canceled | The customer canceled the payment. | New attempt if the customer wishes |
3D Secure declines
decline_code | Default message | Suggested action |
|---|
three_d_secure_failed | 3D Secure authentication failed. The customer may retry. | Retry |
three_d_secure_timeout | The customer did not complete 3D Secure authentication in time. | Retry |
three_d_secure_not_supported | The card does not support 3D Secure authentication. | New method |
three_d_secure_error | 3D Secure verification could not be performed. | Retry |
Processing errors
decline_code | Default message | Suggested action |
|---|
processor_error | A processing error occurred. Please retry. | Retry |
processor_unavailable | The payment processor is temporarily unavailable. Please retry. | Retry |
try_later | Processing is temporarily unavailable. Please retry later. | Retry |
invalid_request | The request was missing a required parameter. | Check the request |
invalid_credentials | The merchant credentials are invalid. | Contact support |
not_found | The requested resource could not be found at the gateway. | Contact support |
New decline codes may be added over time. Treat an unrecognized
decline_code like generic_decline: show a neutral decline message and
offer another payment method.
Showing declines to customers
- Map decline codes to your own short, friendly copy; the default
decline_message is written for developers and support staff.
- Never echo raw processor details to customers — they confuse more than they
help and can aid card testing.
- For
lost_card, stolen_card, suspect_fraud, and fraud_filter, show
only a generic “card declined” message. Revealing the real reason tips off
fraudsters.
