---
title: What is 3D Secure?
slug: introducing-3d-secure-2
docTags: 
createdAt: 2024-05-23T14:27:21.903Z
---

The Payment Services Directive (PSD2), introduced a new regulatory requirement: **Strong Customer Authentication (SCA). **The aim of SCA is to add an **increased layer of security **for card not present transactions, when making mobile and online payments. 

To be compliant with SCA, **3D Secure 2** transactions have additional **authentication** and **transaction **information within the payment flow.

This new version of 3D Secure, offers a better user experience and helps to minimise some of the friction the authentication adds to the checkout flow.

:::hint{type="info"}
We support all versions of the 3D Secure protocol up to and including version 3DS2.2
:::

:::hint{type="warning"}
Under no circumstances should merchants store or log any credit card details unless they are **fully PCI-DSS compliant.**
This falls under your responsibility to ensure you do not produce code which circumvents our toolkits. We do not accept any liability for this.
:::

***

## Mastercard Recommended 3D Secure 2 Fields

From 1 July 2026, **Mastercard recommends** providing the following information for Mastercard 3D Secure authenticated transactions:

- **Cardholder name**
  The cardholder’s full name.
- **Billing address line 1**
  The first line of the cardholder’s billing address.
- **At least one contact method**
  Either the:
  - Cardholder’s email address 
    or 
  - A supported telephone number
- **Phone country code**
  The international dialling code associated with the mobile telephone number, when a mobile number is provided.

Supplying this information may improve issuer authentication and authorisation decisions. These fields are recommended rather than mandatory.

:::hint{type="info"}
Transactions will continue to be processed if the fields are not supplied.
:::

For more information on the field names, formats and locations within each request type, see our [Transaction API Reference](https://docs.judopay.com/api-reference).

***

## Authenticating Requests

Each request to Judopay’s Transaction API requires authentication.

Depending on how you integrate with Judopay, the following methods are recommended to authenticate requests:

- Using our SDKs:
  - `/paymentsession`
- Calling directly to our Transaction API:
  - `/paymentsession`, or
  - TokenSecretAuth
    - The token and secret pair

For more information on authenticating requests, see [Authentication Methods](docId\:ylKW5coh5NQnfQ3j_Wjk2).

***

### Authenticating with Payment Session

The following example takes you through the payment flow using `/paymentsession` to authenticate the transaction.

![3ds2 flow](https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/lYCMP_Y0Vdvv4aLUL-g7T-20260511-112339.png)

::::WorkflowBlock
:::WorkflowBlockItem
Create a `/paymentsession`.
Use the reference returned from the response to populate the request header in Step 2.
:::

:::WorkflowBlockItem
Send the authorisation request with the `/payments` request header, populated with the **reference **received in the `/paymentsession` response.
This step:

1. Checks if the card is enrolled to support 3D Secure 2.
2. Gathers the Device and Card Details.
:::

:::WorkflowBlockItem
The response will determine whether:

1. The consumer is challenged for additional information.
2. The consumer is not challenged, the transaction continues and the consumer is re-directed to the outcome screen.
:::

:::WorkflowBlockItem
If the consumer is challenged in order to process the transaction, the 3D Secure 2 challenge screen is presented to the consumer to enter a code or password.

1. You will be notified via your webhook URL when the consumer has successfully completed the challenge screen.
2. Resume the transaction flow by calling the `/resume3ds` endpoint.
:::

:::WorkflowBlockItem
Authorisation complete.
The consumer is redirected to the outcome screen.
:::
::::

***

### 3D Secure Pass Through

You can use your own 3D Secure authentication provider to perform authentication outside of Judopay. 

Pass the authentication data from your external provider to us, using the `/preauths` or `/payments` endpoint.  
Enter the authentication data into the `threeDSecureMpi` block and we will send the result to the gateway as part of the transaction payload.

:::CodeblockTabs
ThreeDSecure2PaymentWithExternalMpi Example

```json
{
  "cardNumber": "4111111111111111",
  "cv2": "123",
  "expiryDate": "01/25",
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": "826"
  },
  "judoId": "100100100",
  "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
  "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99
  },
  "amount": 1.01,
  "currency": "GBP",
  "cardHolderName": "John Doe",
  "threeDSecureMpi": {
    "dsTransId": "41aadf4c-e73f-4bd1-a0c4-acb2615a32af",
    "cavv": "AJkBCWUyZwAAAABugmKTdAAAAAA=",
    "eci": "02",
    "threeDSecureVersion": "2.3.0"
  }
}
```
:::

For more information, see our [API Reference Documentation](https://docs.judopay.com/api-reference/version-621-latest).

***

## Complete Payment Flow

The complete end-to-end 3D Secure payment flow:

![complete payment flow](https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/7xFIeQOk_58zYmfxhDo3T-20260511-112524.png)

Within the 3D Secure 2 payment flow, once the 3D Secure payment is initiated the Issuer will make a decision on whether they have enough authentication data to proceed with the transaction.
The response will determine whether:

- The consumer is **not challenged**, the authentication is successful and the transaction continues (frictionless flow). 
- The consumer is **challenged** for additional information (challenge flow).

For more information on the frictionless and challenge flows, see [To challenge or not to challenge?](docId\:nnhSdT3Gbi4J2lnTGnIkC)