Errors

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.

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

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

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.

Push to Card Errors

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