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
The Recommended action column reflects typical handling for each response code. Treat it as guidance rather than a fixed rule. The appropriate response can vary by transaction, issuer, and your own risk tolerance. This table may be updated over time, so check back here periodically to make sure you're working from the latest version.
| 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. |