# 3DS Configuration

## Overview

When processing card payments under PSD2 SCA rules, a transaction may be eligible for a **3DS exemption**.
Exemptions can reduce friction by allowing a payment to proceed without an explicit cardholder challenge.

You can also go the other way and [enforce 3DS](#how-to-enforce-3ds-for-a-payment) for a payment that would not otherwise need it.

Exemptions are always subject to issuer and scheme decisioning. Requesting an exemption or challenge preference does not guarantee that outcome.

## How to Request 3DS Exemptions

When creating a payment session via [paymentSessionCreate](/documentation/api/reference/openapi#operation/paymentSessionCreate), you can use the `paymentSettings.threeDs.challengeIndicator` field to specify your 3DS authentication preference.

Setting the `challengeIndicator` field allows you to influence the 3DS flow, such as requesting exemptions for low-risk transactions or enforcing a challenge for higher-security requirements. Here are the available options for this field:

| Value | Description |
|  --- | --- |
| `NoPreference` | No explicit preference. Ryft/provider requests standard 3DS handling. |
| `NoChallengeRequested` | Requests a frictionless flow where possible (challenge not explicitly requested). |
| `ChallengeRequested` | Requests the issuer to challenge the cardholder. |
| `TransactionRiskAnalysisAlreadyPerformed` | Signals that Transaction Risk Analysis (TRA) has already been performed prior to authentication. |


If omitted, no explicit preference is requested.

## Example

Here's an example of how to set the `challengeIndicator` when creating a payment session:

```json Create Payment Session - 3DS Settings Example
{
    "amount": 54550,
    "currency": "GBP",
    "customerEmail": "test@mail.com",
    "paymentSettings": {
        "threeDs": {
            "challengeIndicator": "TransactionRiskAnalysisAlreadyPerformed"
        }
    }
}
```

Please note you can also update the 3DS settings of an existing payment session before attempting payment. This allows you to adjust your 3DS preferences based on the evolving risk profile of the transaction or other factors.

To update the 3DS settings, use the [paymentSessionUpdate](/documentation/api/reference/openapi#operation/paymentSessionUpdate) endpoint with the appropriate `challengeIndicator` value.

## How to Enforce 3DS for a Payment

Whilst we strongly recommend letting the Ryft platform decide when to request 3DS, you can leverage the `paymentSettings.threeDs.policy` field to control this behaviour on a per session basis:

| Value | Description |
|  --- | --- |
| `Default` | 3DS is performed according to your account's 3DS settings. This is the behaviour when `policy` is omitted. |
| `Required` | 3DS is performed for this payment regardless of whether SCA applies. The payment is declined if 3DS is not successfully completed. |


```json Create Payment Session - Enforce 3DS Example
{
    "amount": 54550,
    "currency": "GBP",
    "customerEmail": "test@mail.com",
    "paymentSettings": {
        "threeDs": {
            "policy": "Required"
        }
    }
}
```

You can also enforce 3DS on an existing payment session before attempting payment, using the [paymentSessionUpdate](/documentation/api/reference/openapi#operation/paymentSessionUpdate) endpoint:

```json Update Payment Session - Enforce 3DS Example
{
    "paymentSettings": {
        "threeDs": {
            "policy": "Required"
        }
    }
}
```

The policy can be changed in either direction until payment is attempted. Updating other 3DS settings, such as `challengeIndicator`, keeps the existing policy. An account-level policy of `Required` takes precedence, in which case the session policy is ignored.

`Required` does not apply to:

- MOTO payments
- Merchant-initiated payments that follow a previous payment in a series, for example subsequent recurring or unscheduled payments


Payments that already carry an authentication result, such as Apple Pay and Google Pay cryptograms, are treated as authenticated and are not asked to complete 3DS again.

`policy` controls **whether** 3DS is performed, while `challengeIndicator` controls **how** it is performed. You can combine them, for example `"policy": "Required"` with `"challengeIndicator": "ChallengeRequested"` to perform 3DS and ask the issuer to challenge the cardholder. Requiring 3DS guarantees authentication is requested, but the issuer may still complete it without a challenge.

## Next Steps

- To create and process payments end-to-end, follow [Initial Setup](/documentation/get_started/process_payments).
- To learn more about 3DS, see [3D Secure](/documentation/overview/core_concepts/3ds).