Finix uses an HTTP status code to communicate the success or failure of an API Call:
- A 2xx HTTP status code gets used for all successful API calls.
- A 4xx or 5xx HTTP status code gets used for errors.
For transfer and authorizations, you can test for specific responses and errors.
4xx and 5xx Status Codes
These are the HTTP status codes Finix uses for errors.
HTTP Code | error.code | Description |
---|---|---|
400 |
BAD_REQUEST | You provided a request that can not be successfully parsed. Verify you are providing valid JSON. |
401 |
UNKNOWN | We could not authenticate your request. You used an incorrect API Key. |
402 |
UPSTREAM_PROCESSOR_ERROR | Errors caused by 3rd party service. |
DECLINED | The authorization was declined. Use the failure_code and failure_message for more details. |
|
403 |
FORBIDDEN | Your credentials don't have the right permissions to submit the request. |
404 |
NOT_FOUND | The specified resource could not be found. |
405 |
METHOD_NOT_ALLOWED | The HTTP request method used to submit the request is not supported by the specified resource. |
406 |
NOT_ACCEPTABLE | The server can't accept the submitted request. Double-check how the request was formatted and submitted. |
409 |
CONFLICT | The submitted request conflicts with the current state of the server. |
422 |
UNPROCESSABLE_ENTITY | The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved). |
INVALID_FIELD | A provided field has an invalid value. | |
500 |
SERVER_ERROR | We had a problem with our server. Try again later. |
Error Response Body
All errors return an array of errors
. Below is an example of one error that can be returned from any resource (except Transfers
and Authorizations
).
For Transfer
and Authorization
errors see Transfer and Authorization Errors.
{
"total" : 1,
"_embedded" : {
"errors" : [ {
"logref" : "d4ee0b6cdb67686f0c1ec0780e5b4296",
"message" : "Malformed request. ",
"code" : "BAD_REQUEST",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/merchants"
}
}
} ]
}
}
Response
Field | Description |
---|---|
error.code |
A code to programmatically handle the error. |
error.logref |
A unique identifier for this specific API request and response. |
error.message |
A human-readable description of the error. Not to be coded/programmed to. |
Transfer and Authorization Errors
Some declines, Transfers
, and Authorizations
return a 4xx response when declined. We include additional information in the errors
object about the decline, and the ID of the declined Transfer
or Authorization
in the response.
We still create a Transfer
or Authorization
resource in the background, so you have a clear list of approved and declined payments.
{
"total": 1,
"_embedded": {
"errors": [
{
"logref": "3fe8e6ab1e8cf44f",
"message": "Authorization AUst6ZdywPwe4fbYWrH1zTNJ was declined Cause: Authorization AUst6ZdywPwe4fbYWrH1zTNJ could not be submitted. Cause: Generic Decline",
"code": "DECLINED",
"authorization": "AUst6ZdywPwe4fbYWrH1zTNJ"
"failure_code": "GENERIC_DECLINE",
"failure_message": "The card was declined for an unknown reason. The cardholder needs to contact their issuer for more information.",
"_links": {
"self": {
"href": "https://finix.sandbox-payments-api.com/authorizations"
},
"authorization": {
"href": "https://finix.sandbox-payments-api.com/authorizations/AUst6ZdywPwe4fbYWrH1zTNJ"
}
}
}
]
}
}
Response
Field | Description |
---|---|
error.authorization |
The Authorization ID of the declined authorization. This is only populated for authorization errors that result in a created Authorization . |
error.code |
A code to programmatically handle the error. For Authorizations and Transfers this field is now deprecated in favor of failure_code . |
error.failure_code |
The code of the failure so the decline can be handled programmatically. |
error.failure_message |
A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment. |
error.logref |
A unique identifier for this specific API request and response. |
error.message |
A human-readable description of the error. For Authorizations and Transfers this field is now deprecated in favor of failure_message . |
error.transfer |
The Transfer ID of the declined authorization. This is only populated for transfer errors that result in a created Transfer . |
Failure Codes
When a transaction gets declined, Finix lets you know by returning a failure_code
and failure_message
. The failure_message
in the response details the steps you need to take to complete the payment.
Here's a list that includes some of the most common failure_codes
and their failure_messages
.
attention
These failure codes are only for Finix Flex and Finix Core.
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. |
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_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. |
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_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_NOT_CONNECTED | The card reader isn't connected to a network. Connect the card reader to a network and reattempt the transaction. |
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. |
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. |
GENERIC_DECLINE | The card was declined for an unknown reason. The cardholder 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 card has insufficient funds for the transaction. The cardholder needs to use another card. |
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_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. |
LOST_OR_STOLEN_CARD | The transaction was declined because the card is reported lost or stolen. Don't return the LOST_OR_STOLEN_CARD failure_code and failure_message to cardholders. Instead, return a generic decline. |
MAX_TRANSACTION_AMOUNT_EXCEEDED | The transaction was declined because it exceeded the max transaction amount that's associated with the Merchant . The cardholder needs to reprovision the Merchant with a higher max transaction amount or create a transaction with a lower amount. |
NON_TRANSACTION_ACCOUNT | The account doesn't allow ACH payments or it's reached a transaction limit. |
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 type is not permitted. The cardholder needs to use a different type of card. |
Push to Card Errors
Below are the different error values that the messages
attribute can return for Push to Card.
Error Code | Messages |
---|---|
REFER_TO_CARD_ISSUER | Please contact card issuer for more information. |
INVALID_MERCHANT | Merchant not permitted for this transaction type |
PICK_UP_CARD_NO_FRAUD | Please contact card issuer for more information. |
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 |
PICK_UP_CARD_FRAUD_ACCOUNT | Please contact card issuer for more information. |
INVALID_TRANSACTION | Issuing bank does not support this transaction type on this card. Please contact card issuer for more information. |
INVALID_AMOUNT_OR_CURRENCY | Transaction violates network amount limit. |
INVALID_ACCOUNT_NUMBER | The account number does not exist. Please make sure the account number is correct or contact your issuer. |
NO_SUCH_ISSUER | The issuer can not be found. Please check card number to ensure it is valid. |
RE_ENTER_TRANSACTION | Please attempt transaction again and contact card issuer if it still cannot be processed. |
NO_ACTION_TAKEN | 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. |
FILE_TEMPORARILY_NOT_AVAILABLE | Please contact card issuer for more information. |
NO_CREDIT_ACCOUNT | Issuer has declined the transaction because the card is not a credit account. Please try another card. |
LOST_CARD_PICK_UP_FRAUD_ACCOUNT | Please contact card issuer for more information. |
STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT | Please contact card issuer for more information. |
NOT_SUFFICIENT_FUNDS | Card issuer has declined the transaction as it does not have sufficient funds. |
NO_CHECKING_ACCOUNT | The card is not tied to a checking account and thus cannot be processed. 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. |
EXPIRED_CARD | The expiration date is expired or missing. Please correct and try again. |
INCORRECT_PIN | The PIN is invalid or missing. Please try again with the correct PIN. |
TRANSACTION_NOT_PERMITTED | Transaction not permitted to cardholder. Please contact card issuer for more information. |
SUSPECTED_FRAUD | Please contact card issuer for more information. |
EXCEEDS_APPROVAL_AMOUNT_LIMIT | Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card. |
RESTRICTED_CARD | Card not supported in this region or country. Please contact card issuer for more information. |
TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT | This transaction does not fulfill compliance requirements and cannot be processed. |
EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT | Please attempt with another card or contact card issuer for more information. |
ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED | The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method. |
CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN | The supplied PIN is invalid. |
NEGATIVE_RESULTS | Invalid security code. |
CANNOT_VERIFY_PIN | The PIN is invalid or missing. Please try again with the correct PIN. |
ISSUER_INOPERATIVE | Please attempt transaction again and contact card issuer if it still cannot be processed. |
FINANCIAL_INSTITUTION_NOT_FOUND | The issuer can not be found. Please check card number to ensure it is valid. |
TRANSACTION_NOT_COMPLETED_LAW_VIOLATION | The transaction cannot be completed because it violates a law. |
SURCHARGE_AMOUNT_NOT_SUPPORTED | The supplied surcharge amount is not supported by the issuer. |
TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT | Transaction violates amount limit. |
CARD_AUTHENTICATION_FAILED | Please contact card issuer for more information. |
STOP_PAYMENT_ORDER | Please contact card issuer for more information. |