Failure Codes
When a card is declined, the Tokenizer surfaces a machine-readable failure code
inside the error field of the ErrorResponse passed to your onError
handler. Use it to show the customer an appropriate message and decide whether a retry
makes sense.
Three of these codes map to a specific input field, so the Tokenizer also flags that
field as invalid in the returned validation object:
| Code | Field flagged invalid |
|---|---|
cvv-mismatch | cardCVV |
invalid-card-number | cardNumber |
expired-card | cardExpiration |
Every other code below is a general issuer decline and does not point at a single field.
Soft vs. hard declines
- Soft declines are temporary authorization failures. An action is usually required before running the card again, after which a retry can succeed.
- Hard declines are permanent authorization failures. The card should not be run again — ask the customer for a different card.
Reference
note
The Recommended action column follows standard payment-industry practice. Treat it as guidance, not an exhaustive protocol, and verify against the gateway's current documentation.
| Code | Meaning | Type | Recommended action |
|---|---|---|---|
amount-limit-exceeded | The amount entered exceeds the issuer or approved amount. | Soft | Retry with a smaller amount, or use a different card. |
call-issuer | An issue occurred that must be handled by the card issuer. | Hard | Ask the customer to contact their card issuer before retrying. |
card-not-activated | The card has not been properly unblocked/activated. | Soft | Ask the customer to activate the card with their issuer, then retry, or use a different card. |
cardholder-account-closed | The cardholder's account is closed. | Hard | Do not retry; ask for a different card. |
could-not-route | The financial institution could not be found for routing (invalid receiving institution ID). | Soft | Temporary routing issue — retry shortly, or use a different card. |
cvv-mismatch | The CVV verification failed. | Soft | Ask the customer to re-enter the CVV, and monitor for fraud. |
do-not-honor | The issuer will not allow the transaction. | Hard | Ask the customer to contact their issuer, or use a different card. |
expired-card | The card has expired or the expiration date is missing. | Hard | Verify the expiration date; ask for a valid or different card. |
incorrect-pin | The PIN is incorrect or missing when required. | Soft | Ask the customer to re-enter the PIN. |
insufficient-funds | The card has insufficient funds to complete the transaction. | Soft | Retry with a lesser amount or later, or use a different card. |
invalid-amount | The amount entered is invalid. | Soft | Correct the amount and retry. |
invalid-card-number | The card number is incorrect. | Soft | Ask the customer to re-enter the card number. |
invalid-merchant | The card is not allowed at this merchant or MCC. | Hard | The card can't be used here; ask for a different card. |
invalid-transaction | The transaction is invalid. | Hard | Do not retry as-is; use a different card. |
issuer-not-available | The issuer was unavailable and STIP is not applicable or unavailable. | Soft | Temporary — retry shortly. |
lost-or-stolen | The card was reported as lost or stolen. | Hard | Do not retry; ask for a different card. |
no-such-issuer | The issuer is invalid. | Hard | Use a different card. |
processing-error | The transaction could not be processed due to a processing error. | Soft | Temporary — retry; if it persists, use a different card. |
reenter-transaction | The transaction could not be processed due to an error in message structure or field format. | Soft | Retry the transaction. |
revocation-of-authorization | Revocation of authorization order. | Hard | Do not retry; ask for a different card. |
suspected-fraud | The transaction was declined because of suspected fraud. | Hard | Ask the cardholder to contact their issuer before retrying. |
transaction-not-allowed | The transaction was not allowed. | Hard | Use a different card. |
velocity-limit-exceeded | The transaction exceeds the card or account's withdrawal frequency limit. | Soft | Retry later, or use a different card. |