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 April 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 April 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 April checkout.

In the Pay Order PayByCard action, find the optional parameters request3DS and returnURL.

Inputs

Parameter	Description
`request3DS`	Defaults to `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 April checkout.

Handling a 3D-Secure challenge response

If a 3DS challenge is procured, the PayOrder API will return status code 200 with a ThreeDSAuthorisationRequired response object.

Copy

Copied

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

The URL provided in the redirectURL field 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.

April checkout JavaScript includes a handleThreeDSAuthorisationRequired 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 Pay Order request. In this attempt, use the Confirm3DSComplete action with the threeDSResponse field set to the ThreeDSAuthorisationRequired value return from the first attempt. This enables the April 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.