3D-Secure Utilisation

Important

Merchants using direct API integration who do not wish to enable 3D-Secure on their integration must still be ready to handle payment actions from 3D-Secure as it can be enforced by card issuers. Merchants in this situation can find the relevant information under the sub-heading Handling a 3DS challenge response on this page.

What is 3D-Secure?

3D-Secure (3DS) is a security protocol supported by most major credit and debit card issuers. A 3DS check typically requires customers to perform some form of authentication between submitting a payment and the payment being approved, usually in the form of a unique code sent to the customer via SMS.

Whilst a 3DS challenge adds a minor delay to your checkout process, it provides 3 major benefits:

An extra layer of security and authentication for the cardholder.
A reduction of “unauthorised transaction” chargebacks or disputes.
“Liability shift” - liability for disputed payments can be shifted from the merchant to the card issuer, guaranteeing payment for transactions authenticated by 3D Secure.

Important

Liability shift is not guaranteed and is affected by a number of factors, including the card issuer, type of dispute and type of card used. Likewise, a merchant enabling 3DS in their integration does not guarantee every transaction will produce a 3DS challenge, as it is dependent on card issuer and card type.

Implementing 3DS through plugin integration

Merchants who have integrated Limepay using plugins for e-commerce platforms can enable 3DS on their checkout by finding the toggle in the plugin settings. The plugin will handle the rest of the process.

Implementing 3DS through the Limepay API

Merchants using a direct API integration will need to enact the following to enable 3DS from the merchant side. Understand that enabling 3DS does not guarantee a challenge on every transaction, and choosing to not enable it does not guarantee avoidance of challenges.

Important

Merchants must be using checkout.js version 2.1.0 or greater to enable 3DS through the Limepay checkout.

In the Order [Pay] API, find the optional parameters request3DS and returnURL.

Inputs

Parameter	Description
`request3DS`	default “false”. Change to “true” if you wish to request a 3DS challenge from the customer’s card issuer. Not all cards and issuers have 3DS and this is only a request, so the challenge is not guaranteed to occur. Therefore your integration must be able to handle a `PayOrder` request that can complete normally irrespective of the `request3DS` parameter being set to “true”.
`returnURL`	URL the customer is returned to after the 3DS challenge, as challenges are completed on a site hosted by the card issuer. Should be an appropriate URL in the payment flow.

With these parameters changed, a 3DS challenge will be requested for card payments through the Limepay checkout.

Handling a 3D-Secure challenge response

If a 3DS challenge is procured, the PayOrder API will return a 403 response “PaymentActionRequired”. Limepay currently only has one required action: ThreeDSAuthorisation

Copy

Copied

{
  "paymentToken": "ptkn_1234567",
  "paymentActionRequired": {
    "threeDSAuthorisationId": "some_unique_identifier",
    "redirectURL": "https://the-card-issuer/3ds-challenge"
  }
}

The ThreeDSAuthorisation JSON object contains a redirectURL which must be loaded for the customer. This URL will usually load an iFrame from the card issuer to complete the challenge on their own web services. The customer will be forwarded to the returnURL provided earlier upon completion of the challenge.

Limepay checkout JavaScript includes a handlePaymentActionRequired helper function for displaying a 3DS challenge prompt to the customer. Please refer to the payment action handling documentation for more information.

Confirming the Order Payment

After completing the ThreeDSAuthorisation, your integration should reattempt the PayOrder request. In this attempt, the paymentActionRequired field must be set 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 previously required action.

Additional payment actions could follow, and these must be handled until a payment success or failure response is received.

What's next?

Check the error handling documentation.

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

Return to documentation home.