Skip to main content
3D Secure (3DS) adds an authentication step during card payments. The Payments Library handles 3DS challenges automatically—no additional code required.
For general setup instructions, see Library Setup.

​
How It Works

When 3DS is required:
  1. Customer enters card details (or uses Google Pay/Apple Pay)
  2. Library detects 3DS requirement from the issuer
  3. Authentication challenge displays (popup or iframe)
  4. Customer completes verification (password, SMS code, biometric, or app confirmation)
  5. Result returned to your callback with 3DS data
The library handles the entire flow. Your code receives the result after authentication completes.

​
When 3DS Triggers

3DS may be triggered by:
TriggerDescription
Card issuer requirementBank requires authentication for this card/amount
Regional regulationsPSD2/SCA in Europe, similar rules in other regions
Transaction amountHigh-value transactions often require 3DS
Risk assessmentIssuer flags transaction as requiring verification
Gateway configurationYour PSP settings may require 3DS

​
Supported Payment Methods

Method3DS Support
CardPayYes (automatic)
GooglePayYes (automatic)
ApplePayYes (automatic)
PayPalN/A (uses own authentication)
BankPayN/A (uses bank authentication)

​
3DS Data in Results

After successful 3DS authentication, 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

FieldDescription
version3DS protocol version (e.g., “2.1.0”, “2.2.0”)
eciElectronic Commerce Indicator - liability shift indicator
authenticationValueCardholder Authentication Verification Value (CAVV/AAV)
xidTransaction identifier
sliService Level Indicator (Mastercard only)

​
ECI Values

The ECI indicates the authentication result and liability:
ECIVisa/AmexMastercardMeaning
0502Fully authenticatedLiability shift to issuer
0601Attempted (issuer not enrolled)Liability shift to issuer
0700Not authenticatedNo 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. When configuring your PSP in Orchestra, ensure:
  1. PSP supports 3DS (check with your provider)
  2. 3DS credentials are configured in your PSP account
  3. threeDsAccountName is set when creating sessions (if using a separate 3DS provider)
// Server-side session creation with 3DS account
const session = {
  operation: 'CHARGE',
  amount: 100.00,
  currencyCode: 'USD',
  mode: 'LIVE',
  paymentGatewayAccountId: 'your-psp',
  threeDsAccountName: 'your-3ds-account'  // Optional: if using separate 3DS provider
};

​
Frictionless vs. Challenge Flow

3DS 2.x supports two flows:
FlowDescriptionUser Experience
FrictionlessRisk-based authentication passes silentlyNo interruption
ChallengeUser must complete verificationPopup/redirect
The library handles both flows automatically. Frictionless authentication completes without user interaction when the issuer’s risk assessment allows it.

Card Payments

CardPay setup and results

Digital Wallets

Google Pay, Apple Pay

Library Reference

Full API reference

PSP Setup

Configure payment processor