# 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](/developer-portal/three-d-secure#handling-a-3d-secure-challenge-response)** on this page.

## What is 3D-Secure?

**[3D-Secure (3DS)](https://en.wikipedia.org/wiki/3-D_Secure)** 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:

1. An extra layer of security and authentication for the cardholder.
2. A reduction of “unauthorised transaction” chargebacks or disputes.
3. “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](/openapi/april-public/orders/payorder) `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.


```json
{
  "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](/developer-portal/error-handling#handling-payment-actions)** documentation for more information.

### Confirming the Order Payment

After completing the `ThreeDSAuthorisation`, your integration should reattempt the [Pay Order](/openapi/april-public/orders/payorder) 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](/developer-portal/error-handling)** documentation.

Visit the **[testing](/developer-portal/testing)** page to confirm the integration is fully functional.

br
br
**[Return to documentation home](/).**