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, or use your own 3DS authentication if you perform 3DS yourself.
Exemptions are always subject to issuer and scheme decisioning. Requesting an exemption or challenge preference does not guarantee that outcome.
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.
Here's an example of how to set the challengeIndicator when creating a payment session:
{
"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.
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. |
{
"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:
{
"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.
If you perform 3DS with your own 3DS server (MPI), you can send its result in the authenticationParameters field when calling attempt-payment with your secret API key. Ryft then uses your authentication result instead of performing 3DS for the payment.
Your account must be enabled to send its own 3DS results. Contact Ryft to have this enabled.
| Field | Description |
|---|---|
eci | Required. The Electronic Commerce Indicator returned by the authentication: 00, 01, 02, 05, 06, 07, N0 or N2. |
authenticationValue | The base64 encoded authentication value (CAVV / AAV). Required unless eci is 00, 07 or N0. |
protocolVersion | The 3DS protocol version used: 2.1.0 or 2.2.0. Required unless eci is 00, 07 or N0. |
threeDsServerTransactionId | The transaction ID assigned by the 3DS server. |
acsTransactionId | The transaction ID assigned by the issuer's Access Control Server. |
dsTransactionId | The transaction ID assigned by the card scheme Directory Server. Required unless eci is 00, 07 or N0. |
All transaction IDs must be UUIDs.
Call paymentSessionAttemptPayment with your secret API key, with either cardDetails or a stored card in paymentMethod. Sending cardDetails from your server requires you to be PCI SAQ-D compliant, see Server-To-Server Payments.
{
"clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
"cardDetails": {
"number": "4444333322221111",
"expiryMonth": "10",
"expiryYear": "2028",
"cvc": "100"
},
"authenticationParameters": {
"eci": "05",
"authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
"protocolVersion": "2.2.0",
"dsTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
}
}When you send your own 3DS result:
threeDsRequestDetailsis not used to perform 3DS, but you can still send it so the customer's device details can be used in fraud screening.- If the issuer declines the payment because authentication is required (
3ds_authentication_required), Ryft does not retry the payment with 3DS. Perform authentication again with your 3DS server and make a new payment attempt. - An
eciof00,07orN0means the cardholder was not authenticated, so the payment is declined with3ds_authentication_failurewithout being sent for authorization. - An
eciofN0orN2(Mastercard zero-value authentication) is accepted on any payment session.
You cannot send your own 3DS result with walletDetails, a stored Apple Pay or Google Pay payment method, or for a MOTO payment or a subsequent payment in a series. To send an Apple Pay or Google Pay token you have decrypted yourself, see Decrypted Apple Pay and Google Pay Tokens.
If a request with authenticationParameters is not valid, it is rejected with a 400. The errors you are most likely to see are:
| Error | Reason |
|---|---|
'authenticationParameters' cannot be supplied when using your public api key | authenticationParameters was sent to attempt-payment with your public API key. Call it from your server with your secret API key. |
'authenticationParameters' is not enabled on your account - please contact support | Your account is not enabled to send its own 3DS results. |
'authenticationParameters' cannot be supplied with 'walletDetails' | Your own authentication result cannot be sent with a token Ryft decrypts. Send a decrypted wallet token if you decrypt the token yourself. |
'authenticationParameters' cannot be supplied when paying with a stored wallet payment method | Your own authentication result cannot be sent with a stored Apple Pay or Google Pay payment method, as it already carries its own authentication. |
'authenticationParameters' cannot be supplied for payment session '<id>' as it is out of scope for 3DS (MOTO or a subsequent payment in a series) | The payment session is a MOTO payment or a subsequent payment in a series, which are not subject to 3DS. |
authenticationParameters.eci must be provided | eci is required when sending your own 3DS result with card details or a stored card. |
authenticationParameters.<field> must be provided for eci '<eci>' | A field required for the eci you sent is missing, for example dsTransactionId with an eci of 05. |
- To create and process payments end-to-end, follow Initial Setup.
- To learn more about 3DS, see 3D Secure.