3D Secure API Reference
This page describes how to include 3D Secure 2.0 data in your payment requests. By passing additional cardholder and browser details, you help xMoney and issuers accurately authenticate cardholders under PSD2 (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.
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
Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property
Boolean that represents the ability of the cardholder browser to execute JavaScript.
Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
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.
Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.
Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.
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.
The city of the Cardholder billing address associated with the card used for this purchase.
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)
First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.
The state or province of the Cardholder billing address associated with the card used for this purchase. Should be the country subdivision code defined
The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. RFC 5322
The home phone number provided by the Cardholder.
The work phone number provided by the Cardholder.
The mobile phone number provided by the Cardholder.
The city of the Cardholder shipping address associated with the card used for this purchase.
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)
The first line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
The second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
The third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
The ZIP or other postal code of the shipping address requested by the Cardholder.
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.
Sending the 3DS Data
- Create a JSON object with the desired fields (see example below).
- Encode the JSON object using Base64.
- Include the resulting string in your payment request under the parameter name threeDSecureData.
Example JSON
{
"Email": "john.doe@test.com",
"addrMatch": "Y",
"billAddrCity": "New York",
"billAddrCountry": "840",
"billAddrLine1": "Madison Ave 104th",
"billAddrLine2": "Building A",
"billAddrLine3": "Apt 123",
"billAddrPostCode": "10001",
"billAddrState": "NY",
"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)",
"cardholderName": "John Doe",
"homePhone": {
"cc": "1",
"subscriber": "2125096995"
},
"mobilePhone": {
"cc": "1",
"subscriber": "2345187886"
},
"workPhone": {
"cc": "1",
"subscriber": "2212366542"
},
"shipAddrCity": "New York",
"shipAddrCountry": "840",
"shipAddrLine1": "Madison Ave 104th",
"shipAddrLine2": "Building A",
"shipAddrLine3": "Apt 123",
"shipAddrPostCode": "10001",
"shipAddrState": "NY"
}Base64-encode this JSON and set it as the value for threeDSecureData.
Example Request
Below is a simplified example (in pseudo-JSON) illustrating how you might send threeDSecureData:
{
"siteId": "YOUR_SITE_ID",
"amount": 100.00,
"currency": "USD",
"description": "Order #1234",
"threeDSecureData": "eyJFbWFpbCI6ICJqb2huLmRvZUB0ZXN0LmNvbSIsICJhZGRyTWF0Y2giOiAiWSIsICJiaWxsQWRkckNpdHkiOiAiTmV3IFlvcmsiLCAuLi59"
}Validation
You can validate your JSON structure against xMoney’s 3DS schema. For a sample schema, you can visit: https://secure-stage.xmoney.com/schema/3ds/3ds.schema.json
Tips:
- 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. For more information on how xMoney handles 3D Secure authentication and challenge flows, refer to our 3D Secure Overview page.