Declines
Understand why certain card payments are declined and how Moov categorizes different types of 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 |
|---|---|---|
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 |
account-not-activated |
The card or account has not been activated | Ask the cardholder to activate the card or account with their issuer, then re-attempt |
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 |
authentication-failed |
Cardholder authentication (for example, 3-D Secure) was attempted, but failed verification | Ask the cardholder to retry authentication with their issuer, or verify authentication details before re-attempting |
authentication-required |
The transaction requires additional cardholder authentication (such as 3-D Secure) before it can be approved | Prompt the cardholder to complete the required authentication step, then re-attempt |
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 |
cardholder-action-required |
Before the transaction can proceed, the cardholder must take an action, such as contacting the issuer or confirming details | Ask the cardholder to contact the issuer, or complete the required verification, then re-attempt |
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 |
duplicate-transaction |
The transaction is a duplicate of one already submitted | Do not re-attempt with the same information. Confirm whether the original transaction succeeded before resubmitting. |
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 |
format-error |
The transaction message contains an invalid or malformed field | Do not re-attempt without correcting the request. Review transaction fields for formatting issues or contact support |
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-pin |
The PIN provided is invalid | Please re-attempt with a valid PIN |
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 |
offline-approved |
The transaction was approved offline by the card's chip without online issuer authorization | No action required. These transactions settle through normal offline-authorization processing. |
offline-declined |
The transaction was declined offline by the card's chip without online issuer authorization | Ask the cardholder to try a different card or payment method |
partial-approval |
Only part of the requested amount was approved, typically due to a balance limit on a prepaid or gift card | Confirm the approved amount with the cardholder and collect the remaining balance through another payment method |
payment-stopped |
The cardholder has requested that the payment (for example, a recurring payment) be stopped | Do not re-attempt with the same information. Contact the cardholder to confirm whether the payment should be canceled. |
pin-required |
A PIN is required to complete the transaction but was not provided | Re-attempt the transaction with a PIN |
processing-error |
The transaction could not be processed due to processing error | Ensure payment details are valid or contact issuer for more information |
record-not-found |
The original transaction record referenced could not be found | Verify the original transaction details before re-attempting |
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 |
surcharge-not-permitted |
A surcharge was applied, but surcharging is not permitted for this card or region | Remove the surcharge and re-attempt the transaction |
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 |
transaction-reversed |
The original transaction has been reversed | Typically, no further action is required. Confirm the reversal with the cardholder or issuer if unexpected. |
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 |
verification-failed |
Card or account verification failed | Please verify the card details and re-attempt with updated information |