# 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).
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`


```json
{
  "$ref": "#/components/schemas/3d-params.schema",
  "components": {
    "schemas": {
      "3d-params.schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "xmoney.threeDSecureData.schema.json",
        "type": "object",
        "title": "xMoney 3DS Data",
        "properties": {
          "addrMatch": {
            "type": [
              "string"
            ],
            "enum": [
              "Y",
              "N"
            ],
            "title": "Address Match Indicator",
            "description": "Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same."
          },
          "browserAcceptHeader": {
            "type": "string",
            "title": "Browser Accept Headers",
            "examples": [
              "application/json"
            ],
            "description": "Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.",
            "minLength": 2,
            "maxLength": 2048
          },
          "browserIP": {
            "type": "string",
            "title": "Browser IP Address",
            "default": "",
            "anyOf": [
              {
                "type": "string",
                "format": "ipv4"
              },
              {
                "type": "string",
                "format": "ipv6"
              }
            ],
            "examples": [
              "10.129.2.251",
              "2011:0db8:85a3:0101:0101:8a2e:0370:7334"
            ],
            "description": "IP address of the browser as returned by the HTTP headers to the 3DS Requestor."
          },
          "browserJavaEnabled": {
            "type": "boolean",
            "title": "Browser Java Enabled",
            "examples": [
              true,
              false
            ],
            "description": "Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property"
          },
          "browserJavaScriptEnabled": {
            "type": "boolean",
            "title": "Browser JavaScript Enabled",
            "examples": [
              true,
              false
            ],
            "description": "Boolean that represents the ability of the cardholder browser to execute JavaScript."
          },
          "browserLanguage": {
            "type": [
              "string"
            ],
            "title": "Browser Language",
            "examples": [
              "en"
            ],
            "description": "Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.",
            "maxLength": 8,
            "minLength": 1
          },
          "browserColorDepth": {
            "type": [
              "string"
            ],
            "enum": [
              "1",
              "4",
              "8",
              "15",
              "16",
              "24",
              "32",
              "48"
            ],
            "title": "Browser Screen Color Depth",
            "description": "Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property."
          },
          "browserScreenHeight": {
            "type": [
              "string"
            ],
            "title": "Browser Screen Height",
            "description": "Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.",
            "examples": [
              "1280",
              "768"
            ],
            "pattern": "^[1-9][0-9]{0,5}$"
          },
          "browserScreenWidth": {
            "type": [
              "string"
            ],
            "title": "Browser Screen Width",
            "description": "Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.",
            "examples": [
              "1440",
              "984"
            ],
            "pattern": "^[1-9][0-9]{0,5}$"
          },
          "browserTZ": {
            "type": [
              "string"
            ],
            "title": "Browser Time Zone",
            "examples": [
              "300",
              "-300",
              "+300"
            ],
            "description": "Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.",
            "pattern": "^[\\+\\-]?[0-9]{1,5}$"
          },
          "browserUserAgent": {
            "type": [
              "string"
            ],
            "title": "Browser User-Agent",
            "examples": [
              "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.90 Safari/537.36"
            ],
            "minLength": 2,
            "maxLength": 2048
          },
          "billAddrCity": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address City",
            "description": "The city of the Cardholder billing address associated with the card used for this purchase.",
            "examples": [
              "Bill City Name"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "billAddrCountry": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address Country",
            "description": "The country of the Cardholder billing address associated with the card used for this purchase. Shall be the ISO 3166-1 numeric three-digit country code, other than exceptions listed in Table A.5 (901–999, Reserved by ISO to designate country names not otherwise defined)",
            "examples": [
              "840"
            ],
            "pattern": "^[0-9]{3}$"
          },
          "billAddrLine1": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address Line 1",
            "description": "First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.",
            "examples": [
              "Bill Address Line 1"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "billAddrLine2": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address Line 2",
            "description": "Second line  of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.",
            "examples": [
              "Bill Address Line 2"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "billAddrLine3": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address Line 3",
            "description": "Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.",
            "examples": [
              "Bill Address Line 3"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "billAddrPostCode": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address Postal Code",
            "description": "ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.",
            "examples": [
              "Bill Post Code"
            ],
            "maxLength": 16
          },
          "billAddrState": {
            "type": [
              "string"
            ],
            "title": "Cardholder Billing Address State",
            "description": "The state or province of the Cardholder billing address associated with the card used for this purchase. Should be the country subdivision code defined",
            "examples": [
              "CO"
            ],
            "maxLength": 3
          },
          "Email": {
            "type": [
              "string"
            ],
            "title": "Cardholder Email Address",
            "description": "The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. RFC 5322",
            "examples": [
              "example@example.com"
            ],
            "maxLength": 254,
            "format": "email"
          },
          "homePhone": {
            "type": [
              "object"
            ],
            "title": "Cardholder Home Phone Number",
            "description": "The home phone number provided by the Cardholder.",
            "required": [
              "cc",
              "subscriber"
            ],
            "properties": {
              "cc": {
                "type": [
                  "string"
                ],
                "title": "Country Code",
                "examples": [
                  "123"
                ],
                "pattern": "^[0-9]{1,3}$"
              },
              "subscriber": {
                "type": [
                  "string"
                ],
                "title": "Subscriber",
                "examples": [
                  "123456789"
                ],
                "maxLength": 15
              }
            }
          },
          "workPhone": {
            "type": [
              "object"
            ],
            "title": "Cardholder Work Phone Number",
            "description": "The work phone number provided by the Cardholder.",
            "required": [
              "cc",
              "subscriber"
            ],
            "properties": {
              "cc": {
                "type": [
                  "string"
                ],
                "title": "Country Code",
                "examples": [
                  "123"
                ],
                "pattern": "^[0-9]{1,3}$"
              },
              "subscriber": {
                "type": [
                  "string"
                ],
                "title": "Subscriber",
                "examples": [
                  "123456789"
                ],
                "maxLength": 15
              }
            }
          },
          "mobilePhone": {
            "type": [
              "object"
            ],
            "title": "Cardholder Mobile Phone Number",
            "description": "The mobile phone number provided by the Cardholder.",
            "required": [
              "cc",
              "subscriber"
            ],
            "properties": {
              "cc": {
                "type": [
                  "string"
                ],
                "title": "Country Code",
                "examples": [
                  "123"
                ],
                "pattern": "^[0-9]{1,3}$"
              },
              "subscriber": {
                "type": [
                  "string"
                ],
                "title": "Subscriber",
                "examples": [
                  "123456789"
                ],
                "maxLength": 15
              }
            }
          },
          "cardholderName": {
            "type": [
              "string"
            ],
            "title": "Cardholder Name",
            "examples": [
              "Cardholder Name"
            ],
            "minLength": 2,
            "maxLength": 45
          },
          "shipAddrCity": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address City",
            "description": "The city of the Cardholder shipping address associated with the card used for this purchase.",
            "examples": [
              "Bill City Name"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "shipAddrCountry": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address Country",
            "description": "The country of the Cardholder shipping address associated with the card used for this purchase. Shall be the ISO 3166-1 numeric three-digit country code, other than exceptions listed in Table A.5 (901–999, Reserved by ISO to designate country names not otherwise defined)",
            "examples": [
              "840"
            ],
            "pattern": "^[0-9]{3}$"
          },
          "shipAddrLine1": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address Line 1",
            "description": "The first line of the street address or equivalent local portion of the shipping address requested by the Cardholder.",
            "examples": [
              "Ship Address Line 1"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "shipAddrLine2": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address Line 2",
            "description": "The second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.",
            "examples": [
              "Ship Address Line 2"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "shipAddrLine3": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address Line 3",
            "description": "The third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.",
            "examples": [
              "Ship Address Line 3"
            ],
            "minLength": 1,
            "maxLength": 50
          },
          "shipAddrPostCode": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address Postal Code",
            "description": "The ZIP or other postal code of the shipping address requested by the Cardholder.",
            "examples": [
              "Ship Post Code"
            ],
            "minLength": 1,
            "maxLength": 16
          },
          "shipAddrState": {
            "type": [
              "string"
            ],
            "title": "Cardholder Shipping Address State",
            "description": "The state or province of the shipping address associated with the card used for this purchase. Should be the country subdivision code defined in ISO 3166-2.",
            "examples": [
              "CO"
            ],
            "minLength": 1,
            "maxLength": 3
          }
        },
        "if": {
          "properties": {
            "browserJavaScriptEnabled": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "browserAcceptHeader",
            "browserIP",
            "browserJavaEnabled",
            "browserJavaScriptEnabled",
            "browserLanguage",
            "browserColorDepth",
            "browserScreenHeight",
            "browserScreenWidth",
            "browserTZ",
            "browserUserAgent"
          ]
        }
      }
    }
  }
}
```

## 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.