Handling errors and payment actions

The April checkout is functional and robust, but errors and payment actions will occur in the world of online transactions. It’s important that all errors are dealt with effectively.

Handling errors

April uses HTTP response codes to indicate success and error states. Status codes in the 40x range indicate an error with the client call. Status codes in the 50x range indicate an error on the payment platform side.

Error responses will also include a standardized JSON body providing more details on the error. For example

{
  "statusCode": 400,
  "errorCode": "insufficient_funds",
  "message": "Error encountered trying to process this transaction with the payment gateway",
  "tracer": "8ea3bc8f-0d6d-44bf-971f-14b13e87d98e",
  "detail": "Your card has insufficient funds.; code: card_declined; request-id: req_5gKL3S4wVyzEsc",
  "errorTypeDescription": "The server is unable to process the request due to client error. Most common reasons are a malformed request syntax or values."
}

The fields are:

• statusCode - HTTP status code for this error
• errorCode - An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
• message - Human readable description of the error
• tracer - An unique identifier for the request. Provide this to support team if you wish to query a particular error.
• detail - Optional additional details for the error.
• errorTypeDescription - A description of the category of errors for the given statusCode.

The OpenAPI documentation linked to in this documentation and others lists the possible error codes. Some of the more common errors include HTTP 400 errors, such as insufficient_funds or incorrect_cvc. Please ensure you carefully check the OpenAPI documentation and handle all errors.

Charge Failure Codes

For order payments, the following errorCode's for failed transaction charges can be returned:

Handling 3D-Secure challenges

Your integration must also handle actions returned by the Pay Order API. The PayOrder API can return either a PayOrderComplete object when the payment has been successfully processed, or a ThreeDSAuthorisationRequired object that includes the details you need to handle a 3D-Secure challenge.

Note that several payment actions can be requested. It is important to keep looping until you receive a PayOrderComplete response.

If an action is requested, follow these steps:

1. Use the AprilCheckout.handleThreeDSAuthorisationRequired helper function for displaying action prompts to the customer.

// display action prompt
AprilCheckout.handleThreeDSAuthorisationRequired(
    ThreeDSAuthorisationRequired, // from PayOrder HTTP ThreeDSAuthorisationRequired response
  function () {
    // action completed, reattempt PayOrder request
  },
  function (error) {
    // error handler
  }
);

2. After completing 3DS, your integration should reattempt the PayOrder request using the Confirm3DSComplete action. Set the paymentTokenId and authoriseOnly fields with the same values you used in the original request and set the threeDSResponse object to the value returned on the ThreeDSAuthorisationRequired response. This enables the April API to continue from the interrupted action.
3. Confirm there are no additional payment actions . If there are, repeat the process to handle all actions until a payment success or failure response is finally received.

What's next?

Visit the testing documentation page to confirm the integration is fully functional.

Return to the initial direct API integration landing page.

Return to documentation home.