Finix Failure Codes - WeGive Documentation

When a transaction gets declined, Finix returns a failure_code and failure_message in the API response. The failure_message explains the steps you need to take to complete the payment. This guide covers every failure code Finix uses and what to do when you encounter one. Note on changes: failure_codes will never change without advanced notice. However, failure_messages are subject to change and improvements.

Payment Failure Codes

The table below lists all payment-related failure codes. Codes marked with an asterisk (*) will disable the Payment Instrument — meaning the card or account can no longer be used for future transactions.


Failure Code	Failure Message
`ADDRESS_VERIFICATION_FAILED_RISK_RULES`	The Risk Rules associated to the Merchant declined the transaction. The cardholder needs to create a card with the correct address.
`ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED`	The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method.
`AUTHORIZATION_EXPIRED_OR_ALREADY_CAPTURED`	The authorization is either expired or has already been captured. The cardholder needs to create a new authorization.
`BANK_ACCOUNT_CLOSED`	The bank account has been closed. Contact the account owner and get another method of payment that’s active.
`BANK_ACCOUNT_FROZEN`	The bank account is frozen. Contact the account owner and get another method of payment.
`CALL_ISSUER`	The card was declined for an unknown reason. The cardholder needs to contact their card issuer for more information.
`CANCELLATION_VIA_API`	The transaction was canceled via API before the transaction was completed. The cardholder needs to attempt the transaction again.
`CANCELLATION_VIA_DEVICE`	The cancel button was pressed on the device before the transaction was completed. The cardholder needs to attempt the transaction again.
*`CARD_ACCOUNT_CLOSED`	The card account has been closed. The cardholder should use an active card.
`CARD_NETWORK_ERROR`	There is a problem with the card network. Contact the network for more information.
`CARD_NOT_ACTIVATED_OR_BLOCKED`	The card was declined because it has not been activated or has been temporarily blocked. Please ask the cardholder to activate their card or contact their issuing bank for additional information.
`CARD_NOT_SUPPORTED`	The card does not support this type of purchase. The cardholder needs to contact their issuing bank to make sure their card can be used to make this type of purchase.
`CARDHOLDER_PREVENTED_RECURRING_TRANSACTION`	Cardholder requested that recurring or installment transaction to be stopped.
`COMMUNICATION_ERROR`	There was a network communication error with the host. Check your network connection and retry the transaction.
`CVV_FAILED_RISK_RULES`	The Risk Rules associated with the Merchant declined the transaction. The cardholder needs to create a card with the correct CVV.
`DEVICE_IN_USE`	The device is currently processing a request. Attempt a request again once the request is complete, or within 6 minutes.
`DEVICE_NOT_CONNECTED`	The payment terminal isn’t connected to a network. Connect the payment terminal to a network and reattempt the transaction.
`DEVICE_UNREACHABLE`	The API request could not communicate with the device. Please try again.
`DO_NOT_HONOR`	The card was declined for an unknown reason. The cardholder needs to contact their issuing bank for more information.
`DUPLICATE_TRANSACTION`	A transaction with the same amount and card was approved recently and marked as a duplicate. If this duplicate transaction was intentional, set `check_for_duplicate_transactions` to `false`.
`EXCEEDED_CARDHOLDER_INPUT_TIME_LIMIT`	The cardholder failed to swipe, tap, or dip the card in the expected time window. The cardholder needs to attempt the transaction again.
`EXCEEDS_APPROVAL_LIMIT`	The transaction was declined because it exceeded the daily approval limit for the card. The cardholder needs to use a different card.
`EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT`	The card has exceeded its withdrawal frequency limit. The cardholder needs to use a different card.
`EXPIRED_CARD`	The card has expired. The cardholder needs to use another card that’s not expired.
`FRAUD_DETECTED`	The card was declined for fraud by the processor. The customer should contact their card issuer for more information.
`FRAUD_DETECTED_BY_FINIX`	The card was declined because of suspected fraud by Finix. Please contact Finix for additional information.
`FRAUD_DETECTED_BY_ISSUER`	The card was declined because of suspected fraud by the issuing bank. Please have the cardholder contact their issuing bank for additional information.
`GENERIC_DECLINE`	The transaction was declined for an unknown reason. The account owner needs to contact their issuer for more information.
`INACTIVE_CARD`	The card is inactive. The cardholder needs to activate the card or use an active card.
`INCOMPLETE_TRANSACTION`	The transaction was not completed by the cardholder. The cardholder needs to reattempt the transaction.
`INSUFFICIENT_FUNDS`	The account has insufficient funds for the transaction. The account holder needs to use another method of payment.
*`INVALID_ACCOUNT_NUMBER`	The card number is not valid. The cardholder needs to contact their issuing bank for more information or use another card.
`INVALID_AMOUNT`	The amount exceeds the amount that is allowed on the card. The cardholder needs to check with their issuing bank to see if they can make purchases of that amount.
`INVALID_BANK_ACCOUNT_NUMBER`	The bank account number is not valid. The account holder needs to use a valid account number.
`INVALID_BANK_ACCOUNT_VALIDATION_CHECK`	The provided bank account cannot be used because the routing number is no longer valid. Please check that the account holder’s routing number and account are correct or attempt with another bank account.
`INVALID_CARD`	The card is invalid. The cardholder needs to use another card that is not invalid.
`INVALID_CARD_NUMBER_OR_EXPIRED_CARD`	The card was declined because the issuing bank indicated that the card number is not valid, closed, or the expiration date is invalid.
`INVALID_CVV`	The CVV number is invalid. The cardholder needs to attempt the transaction again using the correct CVV.
`INVALID_ISSUER`	The card number is not associated to a valid card issuing bank. The cardholder needs to contact their issuing bank.
`INVALID_ROUTING_NUMBER`	The bank routing number provided is invalid. The bank account holder needs to provide a valid routing number.
`INVALID_TRANSACTION`	The transaction is not permitted by the issuing bank. The cardholder needs to contact their issuing bank for more information.
`ISSUER_POLICY_VIOLATION`	The card was declined because the issuing bank has an internal rule that prevents the transaction from being permitted. The rule can prohibit certain MCCs, merchant accounts, issuer country codes or other restrictions. Please have the cardholder contact their issuing bank for additional information.
*`LOST_OR_STOLEN_CARD`	The transaction was declined because the card is reported lost or stolen. Do not return this failure code and message to cardholders. Instead, return a generic decline.
`MAX_TRANSACTION_AMOUNT_EXCEEDED`	The transaction was declined because it exceeded the max transaction amount associated with the Merchant. Reprovision the Merchant with a higher max transaction amount or create a transaction with a lower amount.
`NO_BANK_ACCOUNT_FOUND`	The account number is valid; however, the number doesn’t correspond to the account holder or it’s not an open account. The account holder needs to reenter their information with the correct details.
`NON_TRANSACTION_ACCOUNT`	This is a non-transaction account that limits or prevents transactions. Contact your customer and request permission to charge a different bank account.
`PAYMENT_STOPPED`	The customer has stopped the payment with their bank. Contact the customer for details and to arrange payment.
*`PICK_UP_CARD`	The card has been reported as lost or stolen by the cardholder. The cardholder needs to contact their issuing bank.
`RESTRICTED_CARD`	The card has a restriction preventing approval for this transaction. Please contact the issuing bank for a specific reason.
`RESUBMIT_TRANSACTION`	The transaction couldn’t be processed by the issuer for an unknown reason. The cardholder needs to attempt the transaction again. If the transaction is declined again, the cardholder should contact their issuing bank.
`TRANSACTION_NOT_PERMITTED`	The transaction was declined because the card or transaction type is not permitted. The cardholder needs to use a different type of card or attempt a different transaction method.

Push-to-Card Error Codes

Below are the different error values that the messages attribute can return for Push-to-Card transactions.


Error Code	Message
`ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED`	The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method.
`CANNOT_VERIFY_PIN`	The PIN is invalid or missing. Please try again with the correct PIN.
`CARD_AUTHENTICATION_FAILED`	Please contact card issuer for more information.
`CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN`	The supplied PIN is invalid.
`DO_NOT_HONOR`	Please contact card issuer for more information.
`ERROR`	Please attempt transaction again but if it still cannot be processed try again at a later time.
`EXCEEDS_APPROVAL_AMOUNT_LIMIT`	Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card.
`EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT`	Please attempt with another card or contact card issuer for more information.
`EXPIRED_CARD`	The expiration date is expired or missing. Please correct and try again.
`FILE_TEMPORARILY_NOT_AVAILABLE`	Please contact card issuer for more information.
`FINANCIAL_INSTITUTION_NOT_FOUND`	The issuer can not be found. Please check card number to ensure it is valid.
`INCORRECT_PIN`	The PIN is invalid or missing. Please try again with the correct PIN.
`INVALID_ACCOUNT_NUMBER`	The account number does not exist. Please make sure the account number is correct or contact your issuer.
`INVALID_AMOUNT_OR_CURRENCY`	Transaction violates network amount limit.
`INVALID_MERCHANT`	Merchant not permitted for this transaction type.
`INVALID_TRANSACTION`	Issuing bank does not support this transaction type on this card. Please contact card issuer for more information.
`ISSUER_INOPERATIVE`	Please attempt transaction again and contact card issuer if it still cannot be processed.
`LOST_CARD_PICK_UP_FRAUD_ACCOUNT`	Please contact card issuer for more information.
`NEGATIVE_RESULTS`	Invalid security code.
`NO_ACTION_TAKEN`	Please contact card issuer for more information.
`NO_CHECKING_ACCOUNT`	The card is not tied to a checking account and thus cannot be processed. Please try another card.
`NO_CREDIT_ACCOUNT`	Issuer has declined the transaction because the card is not a credit account. Please try another card.
`NO_SAVINGS_ACCOUNT`	The card is not tied to a savings account and thus cannot be processed. Please try another card.
`NO_SUCH_ISSUER`	The issuer can not be found. Please check card number to ensure it is valid.
`NOT_SUFFICIENT_FUNDS`	Card issuer has declined the transaction as it does not have sufficient funds.
`PICK_UP_CARD_FRAUD_ACCOUNT`	Please contact card issuer for more information.
`PICK_UP_CARD_NO_FRAUD`	Please contact card issuer for more information.
`RE_ENTER_TRANSACTION`	Please attempt transaction again and contact card issuer if it still cannot be processed.
`REFER_TO_CARD_ISSUER`	Please contact card issuer for more information.
`RESTRICTED_CARD`	Card not supported in this region or country. Please contact card issuer for more information.
`STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT`	Please contact card issuer for more information.
`STOP_PAYMENT_ORDER`	Please contact card issuer for more information.
`SURCHARGE_AMOUNT_NOT_SUPPORTED`	The supplied surcharge amount is not supported by the issuer.
`SUSPECTED_FRAUD`	Please contact card issuer for more information.
`TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT`	Transaction violates amount limit.
`TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT`	This transaction does not fulfill compliance requirements and cannot be processed.
`TRANSACTION_NOT_COMPLETED_LAW_VIOLATION`	The transaction cannot be completed because it violates a law.
`TRANSACTION_NOT_PERMITTED`	Transaction not permitted to cardholder. Please contact card issuer for more information.
`UNABLE_TO_LOCATE_RECORD`	The account number does not exist. Please make sure the account number is correct or contact your issuer.

​Payment Failure Codes

​Push-to-Card Error Codes

Payment Failure Codes

Push-to-Card Error Codes