> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Secure

> How the Payments Library handles 3D Secure authentication automatically for card payments.

<Info>
  This page is part of the **Payments Library Guides**. Using the REST API instead? See [REST API 3D Secure](/guides/rest-api/3d-secure).
</Info>

**Prerequisites:** Complete the [Library Setup](/guides/library/setup) with a [3DS-capable PSP](https://orchestrasolutions.com/integ-type/3d-secure/).

3D Secure (3DS) adds an authentication step during card payments. The Payments Library handles 3DS challenges automatically. No additional code required.

<Note>
  For general setup instructions, see [Library Setup](/guides/library/setup).
</Note>

## How It Works

1. Card form opens
2. Customer enters card details
3. Library detects 3DS requirement based on CardPay eWallet specification and PSP integration status
4. Authentication challenge displays (popup or iframe)
5. Customer completes verification (password, SMS code, biometric, or app confirmation)
6. Orchestra completes the requested operation
7. 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                  |

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

## 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`:

```javascript theme={null}
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`:

```javascript theme={null}
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](https://orchestrasolutions.com/integ-type/3d-secure/).

When configuring your PSP in Orchestra, ensure:

1. PSP supports 3DS (check with your provider)
2. 3DS credentials are configured in your PSP 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.

## Related

<CardGroup cols={2}>
  <Card title="Supported Payment Methods" icon="credit-card" href="/guides/library/supported-payment-methods">
    CardPay, ApplePay, GooglePay, PayPal, BankPay, UPI
  </Card>

  <Card title="Result Handling" icon="check" href="/guides/library/result-handling">
    Parse and validate payment results
  </Card>

  <Card title="Library Reference" icon="book" href="/guides/library/reference">
    Full API reference
  </Card>

  <Card title="PSP Setup" icon="building-columns" href="/guides/library/psp-setup">
    Configure payment processor
  </Card>
</CardGroup>