Handling errors and payment actions

Important

This page describes a necessary step in the direct API integration process. It assumes the previous checkout integration and payment processing steps have been completed.

If you are using an e-commerce platform such as Magento, Woocommerce or Salesforce, this section is not relevant to your integration of Limepay.

The Limepay 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

Limepay uses HTTP response codes to indicate success and error states. The OpenAPI documentation linked to in this document 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:

Charge Failure Code
`card_declined`
`do_not_honor`
`expired_card`
`fraudulent`
`incorrect_cvc`
`incorrect_number`
`insufficient_funds`
`invalid_cvc`
`invalid_expiry_month`
`invalid_expiry_year`
`not_permitted`
`pickup_card`
`processing_error`
`stolen_card`

Handling payment actions

Your integration must also handle actions returned by the PayOrder API. The PayOrder API can return an HTTP 403 error, which includes 3D-Secure challenges.

Important

Card issuers may force a 3D-Secure challenge even if a merchant has chosen not to integrate it. For this reason your integration must be able to handle these events even if it has not been enabled from the merchant side.

View the 3d-Secure documentation page for more information and integration.

Note that several payment actions can be requested. It is important to keep looping on any 403 responses until all actions have been handled.

If an action is requested, follow these steps:

Use the LimepayCheckout.handlePaymentActionRequired helper function for displaying action prompts to the customer.

Copy

Copied

// display action prompt
LimepayCheckout.handlePaymentActionRequired(
  paymentActionRequired, // from PayOrder HTTP 403 error response
  function () {
    // action completed, reattempt PayOrder request
  },
  function (error) {
    // error handler
  }
);

After completing the payment action , your integration should reattempt the PayOrder request. Set the paymentActionRequired field with the exact JSON payload from the first attempt (the one returned on the 403 response). This enables the Limepay API to continue from the interrupted action (for example, ThreeDSAuthorisation ).
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.