Declines
For troubleshooting purposes, you’ll want to know why cards are declined. In transfers where the source is a card, there are a number of possible failure reasons (usually for the sake of mitigating possible fraud). You can view these reasons in the get a transfer or list transfers endpoints. To view the card decline reason, look for thefailureCode field within cardDetails. If a card payment fails, the card decline reason will also be returned in the synchronous response upon transfer creation.
In a soft decline scenario, there has been a temporary authorization failure and an action will usually be required before running a card again. In a hard decline scenario, there has been a permanent authorization failure, and the card should not be run again. See the table below for a list of card related failure codes, their descriptions, and best practices to follow. While we have provided best practices, note they are suggestions and not exhaustive of all possibilities.
Failure codes
| Failure code | Description | Best practice |
|---|---|---|
amount-limit-exceeded |
The amount entered exceeds issuer or approved amount | Re-attempt with a lesser amount or at a later date so the limit resets. Contact issuer to discuss adjusting limits |
call-issuer |
An issue occurred which must be handled by the card issuer | Contact card issuer for decline reason |
card-not-activated |
The card has not been properly unblocked | Please contact the bank for support or use a different card |
cardholder-account-closed |
The account is closed | Do not re-attempt with the same information - there will be a fee assessed. Re-submit with different credentials or contact issuer |
could-not-route |
The financial institution cannot be found for routing (receiving institution ID is invalid) | Please verify the routing information and re-attempt with updated details |
cvv-mismatch |
The CVV verification failed | Please verify the CVV and re-attempt with updated details. Monitor for potential fraud |
do-not-honor |
The issuer will not allow the transaction | Re-attempt with different credentials or at a later time. Contact issuer for additional support |
expired-card |
The card has expired or expiration date is missing | Please verify the expiration and re-attempt with updated details. Monitor for potential fraud |
incorrect-pin |
The PIN is incorrect or missing when required | Please re-attempt with an updated PIN |
insufficient-funds |
This card has insufficient funds to complete the transaction | Please re-attempt with a lesser amount or at a later time |
invalid-amount |
The amount entered is invalid | Please re-attempt with a different amount |
invalid-card-number |
The card number is incorrect | Do not re-attempt with the same information - there will be a fee assessed. Verify card information and re-submit with different credentials |
invalid-merchant |
The card is not allowed at this merchant or MCC | Re-attempt once the cardholder has confirmed the restriction has been removed |
invalid-transaction |
The transaction is invalid | Do not re-attempt - there will be a fee assessed. Evaluate potential fraud or technical issues |
issuer-not-available |
The Issuer was unavailable for the transaction and STIP is not applicable or not available for this transaction | Can re-attempt the same day. Contact Issuer for additional support |
lost-or-stolen |
The card was reported as lost or stolen | Do not re-attempt with the same information - there will be a fee assessed. Re-submit with different credentials or contact Issuer |
no-such-issuer |
The issuer is invalid | Do not re-attempt - there will be a fee assessed. Evaluate potential fraud or technical issues |
processing-error |
The transaction could not be processed due to processing error | Ensure payment details are valid or contact issuer for more information |
reenter-transaction |
The transaction could not be processed due to an error in message structure or field format | Review Address Verification Result or contact acquirer to evaluate possible format errors |
revocation-of-authorization |
Revocation of authorization order | Do not re-attempt with the same information - there will be a fee assessed. Contact cardholder about the recurring payment cancellation |
suspected-fraud |
The transaction was declined because of suspected fraud | Cardholder should contact issuer and should only re-attempt after receiving confirmation of legitimacy |
transaction-not-allowed |
The transaction was not allowed | Do not re-attempt with the same information - there will be a fee assessed. Re-submit with different credentials or contact issuer |
velocity-limit-exceeded |
The transaction exceeds the card or account’s withdrawal frequency limit | Re-attempt at a later date so the limit resets. Contact issuer to discuss adjusting limits |