This page is part of the Payments Library Guides. Using the REST API instead? See REST API 3D Secure. 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:
| ECI | Visa/Amex | Mastercard | Meaning |
|---|
| 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
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:
| Flow | Description | User Experience |
|---|
| Frictionless | Risk-based authentication passes silently | No interruption |
| Challenge | User must complete verification | Popup/redirect |
