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 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, 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:

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

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 endpoint:

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.
To learn more about 3DS, see 3D Secure.