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

# Forward 3D Secure Parameters to Processors

> Learn how to include 3D Secure (3DS) authentication results in your payment requests when using an external 3DS provider. Improve security and reduce fraud.

## What is 3D Secure (3DS)?

**3D Secure** (also called "3DS") is an extra security layer for online card payments. When required, customers authenticate directly with their bank.

**Why it matters:**

* Reduces fraud
* Helps with liability shift (processor/network dependent)
* Required in some regions (e.g., PSD2)
* May improve approval rates

## 3DS Version Support

Revolv3 supports **EMV 3DS 2.x pass-through only**.

3DS 1.x pass-through is **not supported**.

## The `threeDS` Object

Include the `threeDS` object in your payment request:

```json theme={null}
{
  "threeDS": {
    "cavv": "<cavv-value>",
    "xid": "<xid-value>",
    "dsTransactionId": "<ds-transaction-id>",
    "threeDsVersion": "2.1.0"
  }
}
```

### Field Reference

| Field             | Description                                                         | Required                          | Max Length |
| ----------------- | ------------------------------------------------------------------- | --------------------------------- | ---------- |
| `cavv`            | Cardholder Authentication Verification Value returned by issuer/ACS | Required if `threeDS` is supplied | 40         |
| `xid`             | Transaction identifier from ACS (legacy / optional in 2.x)          | Optional                          | 40         |
| `dsTransactionId` | Directory Server Transaction ID (EMV 3DS 2.x)                       | Optional                          | 36         |
| `threeDsVersion`  | EMV 3DS protocol version (`2.1.0`, `2.2.0`, `2.3.0`)                | Required for 3DS                  | -          |

**Note:**\
`dsTransactionId` is the Directory Server *Transaction* ID (transaction-level identifier), not a Directory Server ID.

***

## Example Request

```json theme={null}
{
  "paymentMethod": {
    "creditCard": {
      "paymentAccountNumber": "4111111111111111",
      "expirationDate": "0330",
      "securityCode": "737"
    }
  },
  "threeDS": {
    "cavv": "AAABBIIFmAAAAAAAAAAAAAAAAAA",
    "dsTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDsVersion": "2.1.0"
  },
  "invoice": {
    "amount": {
      "value": 1.03,
      "currency": "USD"
    }
  }
}
```

***

## Troubleshooting

### Common Issues

* Missing `threeDsVersion`
* Unsupported `threeDsVersion`
* Invalid base64 format in `cavv`

### Worldpay Sandbox Note (Base64 Padding)

Some Worldpay sandbox scenarios may reject `cavv` values that include trailing base64 padding (`=`).

If you experience unexplained validation failures:

Example:

```text theme={null}
AAABBIIFmAAAAAAAAAAAAAAAAAA=   may fail
AAABBIIFmAAAAAAAAAAAAAAAAAA    may succeed
```

Only remove trailing `=` padding if required. Do not modify any other characters.

***

## Best Practices

* Send values exactly as received from your 3DS provider
* Only include fields your provider returned
* Ensure `threeDsVersion` matches the version used
* Test thoroughly in sandbox before production rollout

***