# 3D Secure API Reference

This page describes how to include **3D Secure 2.0** data in your [payment requests](/api/reference/order/create-an-order#order/create-an-order/t=request&path=threedsecuredata).
By passing additional cardholder and browser details, you help xMoney and issuers accurately authenticate cardholders under
[PSD2](https://www.ecb.europa.eu/press/intro/mip-online/2018/html/1803_revisedpsd.en.html) (Strong Customer Authentication) requirements and reduce fraud risks.

## Overview

To use **3D Secure 2.0** with xMoney, you can include a parameter named `threeDSecureData` in your payment request.
This parameter should contain a **Base64-encoded JSON object** that holds the relevant cardholder and browser information.

**💡 Auto-Collection Feature:** If you do not send `threeDSecureData`, xMoney will automatically collect some basic data (e.g., IP address, user agent, JavaScript availability) from the shopper's browser.
By providing your own data through `threeDSecureData`, you override what xMoney automatically collects.

## Request Parameter: `threeDSecureData`

## Sending the 3DS Data

Follow these **3 simple steps** to implement 3D Secure data in your payment requests:

**Step 1:** 📝 Create a JSON object with the desired fields (**see example below**).

**Step 2:** 🔤 Encode the JSON object using **Base64** encoding.

**Step 3:** 📤 Include the resulting string in your payment request under the parameter name `threeDSecureData`.

## Example JSON

Below is a comprehensive example showing all available 3D Secure parameters:


```json
{
  // Customer Information
  "Email": "john.doe@test.com",
  "cardholderName": "John Doe",
  
  // Billing Address
  "addrMatch": "Y",
  "billAddrCity": "New York",
  "billAddrCountry": "840",
  "billAddrLine1": "Madison Ave 104th",
  "billAddrLine2": "Building A",
  "billAddrLine3": "Apt 123",
  "billAddrPostCode": "10001",
  "billAddrState": "NY",
  
  // Browser Information
  "browserJavaScriptEnabled": false,
  "browserJavaEnabled": false,
  "browserAcceptHeader": "application/json",
  "browserColorDepth": "16",
  "browserIP": "172.16.254.1",
  "browserLanguage": "en",
  "browserScreenHeight": "920",
  "browserScreenWidth": "1280",
  "browserTZ": "-300",
  "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  
  // Contact Information
  "homePhone": {
    "cc": "1",
    "subscriber": "2125096995"
  },
  "mobilePhone": {
    "cc": "1",
    "subscriber": "2345187886"
  },
  "workPhone": {
    "cc": "1",
    "subscriber": "2212366542"
  },
  
  // Shipping Address
  "shipAddrCity": "New York",
  "shipAddrCountry": "840",
  "shipAddrLine1": "Madison Ave 104th",
  "shipAddrLine2": "Building A",
  "shipAddrLine3": "Apt 123",
  "shipAddrPostCode": "10001",
  "shipAddrState": "NY"
}
```

**⚠️ Important:** **Base64-encode** this JSON and set it as the value for `threeDSecureData` in your payment request.

## Example Request

Below is a simplified example showing how to include `threeDSecureData` in your payment request:


```json
{
  // Basic Payment Information
  "siteId": "YOUR_SITE_ID",
  "amount": 100.00,
  "currency": "USD",
  "description": "Order #1234",
  
  // 3D Secure Data (Base64-encoded JSON from above)
  "threeDSecureData": "eyJFbWFpbCI6ICJqb2huLmRvZUB0ZXN0LmNvbSIsICJhZGRyTWF0Y2giOiAiWSIsICJiaWxsQWRkckNpdHkiOiAiTmV3IFlvcmsiLCAuLi59" 
}
```

**💡 Pro Tip:** The `threeDSecureData` value shown above is a truncated example. Your actual Base64 string will be much longer when encoding the complete JSON object.

## Validation

### Schema Validation

You can validate your JSON structure against xMoney's 3DS [Schema](/assets/3ds-schema.c2fbd19f1cb4d7083a51f9361ff64436a8f49c491669060ac0dbab9f52698ee6.4d383a65.json)

### Validation Checklist

| Step | Description | Status |
|  --- | --- | --- |
| **1** | Ensure JSON is well-formed and valid | ⬜ |
| **2** | Verify all required fields are present | ⬜ |
| **3** | Check field values are within acceptable ranges | ⬜ |
| **4** | Confirm Base64 encoding is correct | ⬜ |


**⚠️ Critical:** Use a JSON validator to ensure your data is well-formed. If any field is incorrect or out of range, the 3D Secure flow may be affected or fail entirely.

## Conclusion

By including detailed **3D Secure 2.0** data in your payment requests, you help xMoney and card issuers verify cardholder
identities more accurately—**reducing fraud** and delivering a **smoother checkout experience**.

### Next Steps

- 📖 Learn more: [3D Secure Overview page](/guides/payments/3d-secure/3d-secure)
- 🛠️ Implement: Use the examples above to start integrating
- ✅ Test: Validate your implementation with our schema
- 🚀 Deploy: Go live with enhanced security


**🎯 Key Benefits:** Enhanced security, reduced fraud, PSD2 compliance, and improved user experience.