3D Secure

This page is part of the Payments Library Guides. For 3D Secure in backend-initiated flows, see REST API 3D Secure.

Prerequisites: Complete the Library Setup with a 3DS-capable PSP, and configure your 3DS merchant details on the CardPay eWallet account. 3D Secure (3DS) adds an authentication step during card payments. The Payments Library handles 3DS challenges automatically, so no additional code is required on your side. Configuration is still required: see the prerequisites above.

Enabling Perform 3Ds? on a CardPay eWallet account without supplying your own 3DS merchant details will cause every 3DS transaction to fail. Orchestra has no default 3DS merchant. See 3DS Merchant Details.

For general setup instructions, see Library Setup.

How It Works

Card form opens
Customer enters card details
Library detects 3DS requirement based on CardPay eWallet specification and PSP integration status
Authentication challenge displays (popup or iframe)
Customer completes verification (password, SMS code, biometric, or app confirmation)
Orchestra completes the requested operation
On completion, the transaction results, including the 3DS data, are returned to the client, ready to be sent to your server for validation

The library handles the entire flow automatically.

When to Trigger 3DS?

You may want to use 3D Secure on your transactions in any of the following use cases:

Use Case	Description
Card issuer requirement	Bank requires authentication for this card/amount
Regional regulations	PSD2/SCA in Europe, similar rules in other regions
Transaction amount	High-value transactions often require 3DS
Risk assessment	Issuer flags transaction as requiring verification
Gateway configuration	Your PSP settings may require 3DS

We recommend using 3DS to authenticate all transactions, even when not required. 3DS provides merchants with liability shift protection and peace of mind knowing that the payer has been fully and properly authenticated.

Supported Payment Methods

Method	3DS Support
CardPay	Yes (automatically by Orchestra)
ApplePay	Yes (automatically by ApplePay)
GooglePay	Partial, depending on device type (automatically by GooglePay)
PayPal	N/A (uses own authentication)
BankPay	N/A (uses bank authentication)
UPI	N/A

3DS Data in Results

After successful 3DS authentication and completion of the transaction, the result includes authentication data in tokenAndMaskedCardModel.threeDS:

const [data] = engine.parseResultToken(result.token);

if (data.tokenAndMaskedCardModel?.threeDS) {
  const tds = data.tokenAndMaskedCardModel.threeDS;

  console.log('Version:', tds.version);           // "2.1.0", "2.2.0", etc.
  console.log('ECI:', tds.eci);                   // Electronic Commerce Indicator
  console.log('Auth value:', tds.authenticationValue);  // CAVV/AAV
  console.log('XID:', tds.xid);                   // Transaction ID
  console.log('SLI:', tds.sli);                   // Service Level Indicator (Mastercard)
}

ThreeDS Fields

Field	Description
`version`	3DS protocol version (e.g., “2.1.0”, “2.2.0”)
`eci`	Electronic Commerce Indicator, liability shift indicator
`authenticationValue`	Cardholder Authentication Verification Value (CAVV/AAV)
`xid`	Transaction identifier
`sli`	Service Level Indicator (Mastercard only)

ECI Values

The ECI indicates the authentication result and liability:

Visa/Amex ECI	Mastercard ECI	Authentication Result	Liability
05	02	Fully authenticated	Liability shift to issuer
06	01	Attempted (issuer not enrolled)	Liability shift to issuer
07	00	Not authenticated	No liability shift

Handling 3DS Failures

If 3DS authentication fails, the payment will not complete. The callback receives a result with clientSuccess: false:

function handleResult(result) {
  if (!result) {
    // User cancelled
    return;
  }

  const [data] = engine.parseResultToken(result.token);

  if (!data.clientSuccess) {
    // Payment failed - could be 3DS failure
    console.error('Payment failed:', data.clientErrorMessage);
    return;
  }

  // Payment successful
}

PSP Requirements

3DS requires a payment processor that supports 3DS connections. Not all PSPs support 3DS for all card types. See the list of integrations that support 3DS. When configuring your PSP in Orchestra, ensure:

PSP supports 3DS (check with your provider)
3DS credentials are configured in your PSP account
Your own 3DS merchant details (acquirer BIN, MID and MCC per card brand) are entered on the CardPay eWallet account

Frictionless vs. Challenge Flow

3DS 2.x supports two flows:

Flow	Description	User Experience
Frictionless	Risk-based authentication passes silently	No interruption
Challenge	User must complete verification	Popup/redirect

The library handles both flows automatically. Frictionless authentication completes without user interaction when the issuer’s risk assessment allows it.

Supported Payment Methods

CardPay, ApplePay, GooglePay, PayPal, BankPay, UPI

Result Handling

Parse and validate payment results

Library Reference

Full API reference

PSP Setup

Configure payment processor

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

How It Works

When to Trigger 3DS?

Supported Payment Methods

3DS Data in Results

ThreeDS Fields

ECI Values

Handling 3DS Failures

PSP Requirements

Frictionless vs. Challenge Flow

Supported Payment Methods

Result Handling

Library Reference

PSP Setup

​How It Works

​When to Trigger 3DS?

​Supported Payment Methods

​3DS Data in Results

​ThreeDS Fields

​ECI Values

​Handling 3DS Failures

​PSP Requirements

​Frictionless vs. Challenge Flow

​Related

Supported Payment Methods

Result Handling

Library Reference

PSP Setup

How It Works

When to Trigger 3DS?

Supported Payment Methods

3DS Data in Results

ThreeDS Fields

ECI Values

Handling 3DS Failures

PSP Requirements

Frictionless vs. Challenge Flow

Related