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

# 3D Secure

> Configure 3DS authentication for card payments.

3D Secure (3DS) adds a verification step where customers authenticate with their bank before a payment is authorized. This reduces fraud, lowers chargebacks, and shifts liability to the issuer for authenticated transactions.

## Why Use 3DS

The EU requires 3DS for online payments under <Tooltip tip="PSD2—EU Payment Services Directive requiring Strong Customer Authentication.">PSD2</Tooltip>'s *<Tooltip tip="SCA—two-factor authentication required for EU online payments.">Strong Customer Authentication (SCA)</Tooltip>* rules. Even in regions without mandates, 3DS reduces fraud and chargebacks while improving issuer approval rates.

## How to Configure 3DS

PayNext uses its own external 3DS2 to generate processor-agnostic cryptograms. This lets you switch processors without re-authenticating customers.

### 3DS Modes

| Mode             | When to use                                                    | Behavior                                                                                                                                           |
| :--------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Adaptive**     | EU/UK merchants, high-risk transactions                        | Runs 3DS on every payment. Accepts challenge or frictionless outcome.                                                                              |
| **Frictionless** | Low-risk or returning customers, US and other non-PSD2 markets | Requests silent authentication. If approved, liability shifts. If challenge required, 3DS is skipped and payment proceeds without liability shift. |
| **No 3DS**       | Regions without 3DS requirements or adoption                   | Skips authentication entirely.                                                                                                                     |

### Set Up 3DS

<Steps>
  <Step title="Get acquirer credentials">
    Request **BIN** and **Acquirer Merchant Identifier (CAID)** from your payment processor representative.
  </Step>

  <Step title="Configure processor 3DS settings">
    Go to **Dashboard → Integrations → \[Processor] → 3DS** and add the **BIN**, **CAID**, and **Country** for each network.
  </Step>

  <Step title="Enable in workflow">
    In your workflow, select **Authorize payment → Configure** and choose your **3D Secure** mode.
  </Step>
</Steps>

## Customer-Initiated Transactions (CIT)

CIT is the standard 3DS flow — the customer is present and completes authentication (challenge or frictionless) during checkout. The PayNext Web SDK handles this automatically based on your workflow settings. Workflows can trigger 3DS based on metadata, issuer country, currency, and other parameters.

Successful CIT authentication is also required if you want to use 3RI for future recurring charges.

| Payment Type                     | 3DS Behavior                                                                         |
| :------------------------------- | :----------------------------------------------------------------------------------- |
| **Cards**                        | PayNext triggers 3DS based on your workflow. Customer authenticates during checkout. |
| **Apple Pay**                    | 3DS embedded — customer authenticates with biometrics.                               |
| **Google Pay (CRYPTOGRAM\_3DS)** | 3DS embedded — behaves like Apple Pay.                                               |
| **Google Pay (PAN\_ONLY)**       | Works like cards. PayNext runs 3DS on the raw card data.                             |

<Note>
  Enabling 3DS for Google Pay only affects PAN\_ONLY payments — CRYPTOGRAM\_3DS already includes 3DS. See [Google Pay Card Parameters](https://developers.google.com/pay/api/web/reference/request-objects#CardParameters) for details.
</Note>

<Accordion title="Identify Google Pay token type">
  Check `payment_method.details`:

  ```json theme={"system"}
  {
    "details": {
      "is_network_tokenized": true,
      "token_service_provider": "Google"
    }
  }
  ```

  When `token_service_provider` is `"Google"`, the payment used CRYPTOGRAM\_3DS.
</Accordion>

## Merchant-Initiated Transactions (MIT)

MIT covers recurring charges, subscription renewals, and saved card transactions — the customer is not present and cannot complete a 3DS challenge. PayNext handles these with either MIT exemptions or 3RI.

| Method            | Liability shift        | Requirement                   |
| :---------------- | :--------------------- | :---------------------------- |
| **MIT exemption** | No                     | None                          |
| **3RI**           | Yes (if authenticated) | Successful 3DS on initial CIT |

### 3RI (3DS Requester Initiated)

3RI authenticates recurring payments without customer interaction, providing liability shift when successful. It requires 3DS completion on the initial CIT and must meet network 3RI rules (see below).

| Payment Type                     | 3RI Support               |
| :------------------------------- | :------------------------ |
| **Cards**                        | Yes (network rules apply) |
| **Apple Pay**                    | No — uses MIT exemptions  |
| **Google Pay (CRYPTOGRAM\_3DS)** | No — uses MIT exemptions  |
| **Google Pay (PAN\_ONLY)**       | Yes (same rules as cards) |

<Accordion title="Network 3RI rules">
  * **Mastercard (SCA markets)**: 3RI succeeds only when MIT amount ≤ original CIT amount
  * **Mastercard (other markets)**: Higher amounts often accepted, but varies by issuer
  * **Visa**: No amount restrictions

  If 3RI is declined, PayNext falls back to MIT exemption.
</Accordion>

## Payment Payload

Each payment includes a `three_d_secure` object with authentication results. If 3DS is skipped, this field is `null`.

```json theme={"system"}
{
  "payment": {
    "id": "pay_123",
    "status": "authorized",
    "three_d_secure": {
      "transaction_id": "3d3e244f-9740-48c8-91af-43f4da039c18",
      "version": "2.2.0",
      "authentication_flow": "challenge",
      "electronic_commerce_indicator": {
        "value": "02",
        "result": "fully-authenticated",
        "liability_shift": true
      },
      "status": "success",
      "status_reason": null
    }
  }
}
```

### Field Reference

| Field                                           | Description                               | Values                                                  |
| :---------------------------------------------- | :---------------------------------------- | :------------------------------------------------------ |
| `transaction_id`                                | Directory server transaction ID           | `3d3e244f-9740-48c8-91af-43f4da039c18`                  |
| `version`                                       | 3DS protocol version                      | `2.2.0`                                                 |
| `authentication_flow`                           | How the customer authenticated            | `challenge`, `frictionless`                             |
| `electronic_commerce_indicator.value`           | ECI from issuer (see Reference)           | `00`–`07`                                               |
| `electronic_commerce_indicator.result`          | Authentication result                     | `fully-authenticated`, `attempted`, `not-authenticated` |
| `electronic_commerce_indicator.liability_shift` | Whether liability shifted to issuer       | `true`, `false`                                         |
| `status`                                        | Authentication status                     | `success`, `failure`                                    |
| `status_reason`                                 | Why authentication failed (see Reference) | `suspected-fraud`                                       |

## Failures

When 3DS authentication fails, the payment returns `three_d_secure.status: "failure"` with a `status_reason`. See [Decline Codes](/guides/payments/decline-codes#incomplete-payments) for payment-level error handling.

## Reference

<AccordionGroup>
  <Accordion title="Status reasons">
    `status_reason` explains why authentication failed when `status` is `failure`:

    | Value                                 | Description                                                |
    | :------------------------------------ | :--------------------------------------------------------- |
    | `failed-authentication`               | Cardholder did not provide correct 3DS details             |
    | `card-not-enrolled`                   | Card is not enrolled in 3DS                                |
    | `suspected-fraud`                     | Transaction suspected to be fraudulent                     |
    | `invalid-acquirer-details`            | Acquirer details invalid; update external 3DS settings     |
    | `transaction-cancelled-by-cardholder` | Cardholder cancelled the transaction                       |
    | `unsupported-3ds-version`             | 3DS version not supported                                  |
    | `challenge-required`                  | Challenge required but workflow configured as frictionless |
    | `authentication-timed-out`            | Customer abandoned the flow                                |
    | `acs-unavailable`                     | Access Control Server unavailable                          |
    | `directory-server-unavailable`        | Directory server unavailable                               |
    | `transient-system-failure`            | Transient system failure during authentication             |
    | `invalid-card-details`                | Card details invalid                                       |
    | `transaction-not-permitted`           | Session configuration not permitted for this card          |
    | `protocol-error`                      | Protocol error during 3DS authentication                   |
  </Accordion>

  <Accordion title="ECI values (Mastercard)">
    | ECI  | Meaning                             | Liability shift    |
    | :--- | :---------------------------------- | :----------------- |
    | `00` | Not authenticated                   | No                 |
    | `01` | Attempted (stand-in) authentication | Yes                |
    | `02` | Successful authentication           | Yes                |
    | `04` | Data-only authentication            | No                 |
    | `06` | Transaction exempt from SCA         | No                 |
    | `07` | Recurring transaction authenticated | Yes (initial only) |
  </Accordion>

  <Accordion title="ECI values (Visa, Amex, Discover, Diners, JCB)">
    | ECI  | Meaning                             | Liability shift |
    | :--- | :---------------------------------- | :-------------- |
    | `05` | Successful authentication           | Yes             |
    | `06` | Attempted (stand-in) authentication | Yes             |
    | `07` | Not authenticated                   | No              |
  </Accordion>
</AccordionGroup>