When a payment or refund fails after Flowlix created the object, the object
carries a machine-readable failure_code and a human-readable
failure_message.
Use failure_code to decide what to do next; use failure_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
failure_code | Default message | Suggested action |
|---|
generic_decline | The payment method was declined for an unknown reason. | New method |
do_not_honor | The payment method was declined by the issuer. | New method |
issuer_declined | The payment method was declined by the issuer. | New method |
insufficient_funds | The card has insufficient funds to complete the purchase. | New method |
invalid_number | The card number is invalid. | 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 payment amount is invalid for this payment method. | Check the request |
invalid_currency | The currency is not supported for this payment method. | Check the request |
not_permitted | This payment method is not permitted for this transaction. | New method |
cardholder_limit | The cardholder limit has been exceeded. | New method |
card_velocity_exceeded | The card activity limit has been exceeded. | New method |
lost_card | The card was reported lost. | New method |
stolen_card | The card was reported stolen. | New method |
suspect_fraud | The payment was declined because fraud was suspected. | New method |
fraud_filter | The payment was declined by fraud controls. | New method |
payment_canceled | The customer canceled the payment. | New attempt if the customer wishes |
3D Secure failures
failure_code | Default message | Suggested action |
|---|
three_d_secure_failed | 3D Secure authentication failed. | Retry |
three_d_secure_timeout | 3D Secure authentication timed out. | Retry |
three_d_secure_not_supported | 3D Secure authentication is not supported for this card. | New method |
three_d_secure_error | 3D Secure authentication could not be completed. | Retry |
Processing errors
failure_code | Default message | Suggested action |
|---|
processor_error | A processing error occurred. Please retry. | Retry |
processor_unavailable | The payment processor is temporarily unavailable. Please retry later. | Retry |
invalid_request | Flowlix could not complete the operation because the payment or refund data was invalid. | Check the request |
not_found | The payment operation could not be found. | Contact support |
New failure codes may be added over time. Treat an unrecognized
failure_code like generic_decline: show a neutral failure message and
offer another payment method.
Showing failures to customers
- Map failure codes to your own short, friendly copy; the default
failure_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.
