Back
Introduction
Authentication
Transactions
Fetching Transactions
Test cards
Errors
Sources
Customers
Refunds & Reversals
Voids
Access List
Hosted Payment Page
Recurring Transactions
Dimoco
Konnektive CRM
Checkout Champ

Errors

The conventional HTTP response codes are used to indicate the success or failure of an API request. These can be viewed in Reports > API Logs.

Codes include:

  • 2xx range: these codes indicate success.
  • 4xx range: these codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
  • 5xx range: these indicate an error with the gateway’s servers. Kindly open a ticket with support to resolve these errors.
Error Parameters include the following:

Parameter

errorType

Type

string

Description

The type of error returned.
code
string
Error code.
parameter
string
If the error is parameter-specific, the parameter related to the error.
message
string
A human-readable message providing more details about the error.

The below is an example of an error response:

{
"errors": [
{
"errorType": "invalidRequest",
"code": "validationError",
"parameter": "Amount",
"message": "Amount must be greater than 0"
}
]
}

HTTP status codes

Code

Meaning

Description

200
OK
Everything worked as expected
201
Created
The requested resource is successfuly created
400
Bad Request
The request was unacceptable, often due to missing a required parameter
401
Unauthorized
No valid API key provided
404
Not Found
The requested resource doesn’t exist
415
Unsupported Media Type
Indicates that the server refuses to accept the request because the payload format is in an unsupported format. The format problem might be due to the request’s indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly
5xx
Server Error
Something went wrong on the gateway side

Error types

Type

Description

invalidRequest
Invalid request errors arise when your request has invalid parameters
paymentError
Error related to payment proccess. The most common type of error
authentication_error
Failure to properly authenticate yourself in the request
api_error
API errors cover any other type of problem (e.g., a temporary problem with the gateway’s servers)

Error codes

Code

Message

invalidTransactionStatus
Invalid transaction status
invalidTransactionType
Invalid transaction type
invalidTransactionMethod
Invalid transaction method

invalidPaymentChannel

Invalid payment channel

invalidCvc

Invalid or not provided CVC parameter

invalidRefundAmount

Refund amount needs to be less or equal to available refund amount

declinedByAcquirer

Declined by acquirer

amountTooLarge

The specified amount is greater than the maximum amount allowed

amountTooSmall

The specified amount is less than the minimum amount allowed

maxVolumeExceeded

Max volume exceeded

restrictionByPid

Restriction by Payment ID

restrictionByEmail

Restriction by email

blacklisted

Transaction blacklisted

invalidPaymentSource

Invalid Payment Source

invalidBillingAddressCountry

Invalid Billing AddressCountry

invalidCurrency 

Invalid Currency

declinedByBank

Common decline by bank

declinedByThreeDSecure 

Declined by 3D Secure

authorizationFailure 

Authorization failure

authorizationToTheChannelFailure 

Authorization to the channel failure

channelConnectionError

Channel connection error

channelInvalidRefundRequest

Channel error, invalid refund request

threeDSecureCardNotEnrolled 

The requested card is not 3D Secure enrolled

threeDSecureEnrolmentError

3D Secure Enrolment Error

threeDSecureAuthenticationError 

3D Secure Authentication Error

Troubleshooting Common Errors

400 - Invalid Payment Channel

HTTP Status code

400 BadRequest

Response Error

{
"errors": [
{
"type": "paymentError",
"code": "invalidPaymentChannel",
"message": "Invalid payment channel."
}
]
}

Causes

This error can be returned due to the following:

  • Payment Channel not set up correctly
  • Payment Channel is inactive
  • Smart Routing is not configured
  • The website being used by the merchant is not linked with the payment channel
  • The currency in the request is different from the payment channel setup

Fixes

  • Make sure that the Payment Channel is configured correctly. To do this, go to CRM > Customers. Press on the Customer and Go to the “Related” tab. Press on the Payment Channel and press the “Edit” button to make modifications.
  • The payment channel has to be “Active”. To activate, go to CRM > Customers. Press on the Customer and Go to the “Related” tab. Press on the Payment Channel and press on the 3 dots to Activate.
  • Make sure smart routing for the Payment Channel is enabled and configured correctly. To do this, go to CRM > Customers. Press on the Customer and Go to the “Smart Routing” tab.
  • Make sure that the correct website is added in the Payment Channel configuration. To do this, go to CRM > Customers. Press on the Customer and Go to the “Related” tab. Press on the Payment Channel and press the “Edit” button. Check the “Website” field and make sure the correct website is listed.
  • Check if the currency in the request matches that of the payment channel. To do this, find the request in Reports > API logs. Filter by customer and check the currency in the original request. To check the currency in the payment channel, you can navigate in Smart Routing (go to CRM > Customers. Press on the Customer and Go to the “Smart Routing” tab.)

401 - Authentication Failure

HTTP Status code

401 Unauthorized

Response Error

{
“errors”: [
{
“type”: “authenticationError”,
“code”: “authenticationFailure”,
“message”: “Authentication failure. Please, check your credentials.”
}
]
}

Causes

This error can be caused when creating a new transaction. This error is returned due to the following:

  • Incorrect endpoint
  • Incorrect API Secret

Fixes

  • Make sure the endpoint is set up correctly. The correct endpoint for creating a new transaction is:
POST https://api.quaife.net/v1/transactions/
  • Reset the API secret To do this, the merchant needs to log in to the portal and navigate to Developer Settings > Website Settings > API Keys. Click on the Website Id and press on “reset” (LIVE or TEST). This will generate a new secret which the merchant can now replace in the Postman environment.

MERCHANT

Should you be interested in becoming a merchant, then please fill out the short form below and one of our specialists will be in touch shortly.

SIGN UP

We are delighted that you are considering using Quaife as your payment partner. Fill in the form below & let’s get started.