3D Secure 2.0 data elements

3D Secure 2.0 (3DS 2.0) uses data elements that can be included alongside the standard parameters in a payment request. These additional data elements increase the chances of processing a payment request via the frictionless flow, ensuring a seamless payment experience for your customers.

Required data elements

The following parameters must be included in your payment request.

Parameter
Description

Browser Accept Header
String
required

The exact content of the HTTP Accept headers as sent to the 3DS Requestor from the cardholder’s browser.

Browser IP
String
required

The IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
Length: 45 characters

Browser Java Enabled
Boolean
required

A boolean that represents whether the cardholder's browser can execute Java. The value is returned from the navigator.javaEnabled property.

Browser Language
String
required

A value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
Length: 1 to 8 characters

Browser Colour Depth
String
required

A value representing the bit depth, in bits per pixel, of the colour palette for displaying images. Obtained from the cardholder's browser using the screen.colorDepth property.
Length: 1 to 2 characters

Browser Screen Height
String
required

The total height of the cardholder’s screen in pixels. The value is returned from the screen.height property.
Length: 1 to 6 characters

Browser Screen Width
String
required

The total width of the cardholder’s screen in pixels. The value is returned from the screen.width property.
Length: 1 to 6 characters

Browser Time Zone
String
required

The time difference, in minutes, between UTC time and the local time of the cardholder's browser.
Length: 1 to 5 characters

Browser User Agent
String
required

The exact content of the HTTP user-agent header.

3DS Component Indicator
String
required

Indicates whether the 3DS method successfully completed.
Length: 1 character

Device Channel
String
required

Indicates the type of device being used to initiate the transaction.
Length: 2 characters

SDK App ID
String
required

Universally unique ID created upon all installations and updates of the 3DS Requestor app on a consumer device. This will be newly generated and stored by the 3DS software development kit (SDK) for each installation or update.
Length: <= 36 characters

SDK Encrypted Data
Object
required

A JSON Web Encryption (JWE) object containing data encrypted by the SDK for the directory server (DS) to decrypt.

SDK Ephem Public Key
Object
required

The public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and access control server (ACS).

  • Key
  • String

In the authentication request (AReq), this data element is present as its own object. In the authentication response (ARes), this data element is contained within the ACS Signed Content JSON Web Signature (JWS) Object.
Length: <= 256 characters

SDK Max Timeout
String
required

Indicates the maximum amount of time, in minutes, for all exchanges to take place.
Length: 2 characters

SDK Reference Number
String
required

Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor app, assigned by EMVCo when the 3DS SDK is approved.
Length: <= 32 characters

SDK Transaction ID
String
required

Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
Length: <= 36 characters

Optional data elements

The following data elements are optional, but we highly recommend you include as many of these parameters as you have available in your payment request to increase the chances of a frictionless payment.

Parameter
Description

3DS Requestor Authentication Indicator
String
optional

Indicates the type of authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request.

3DS Requestor Authentication Information
Object
optional

Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.

  • 3DS Request Authentication Data
  • String

Data that documents and supports a specific authentication process.

3DS Requestor Challenge Indicator
String
optional

Indicates whether a challenge is requested for this transaction.
Length: 2 characters

3DS Requestor Prior Authentication Information
Object
optional

Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.

  • 3DS Request Prior Authentication Data
  • String

Data that documents and supports a specific authentication process.

  • 3DS Request Prior Authentication Method
  • String

Mechanism previously used by the cardholder to authenticate to the 3DS Requestor.
Length: 2 characters

  • 3DS Request Prior Authentication Timestamp
  • String

Date and time in UTC of the prior cardholder authentication.
Length: 12 characters

  • 3DS Request Prior Reference
  • String

This data element provides additional information to the ACS to determine the best approach for handling a request.
Length: 36 characters

Account Type
String
optional

Indicates the type of account (e.g., a multi-account card product).
Length: 2 characters

Address Match
String
optional

Indicates whether the cardholder's shipping address and billing address are the same.

Broad Information
Object
optional

Unstructured information sent between the 3DS Server, the DS and the ACS.

Card Expiry Data
String
optional

The expiry date of the primary account number (PAN) or token supplied to the 3DS Requestor by the cardholder.
Length: 4 characters

Account Information
Object
optional

Additional information about the cardholder’s account provided by the 3DS Requestor.

  • Account Age Indicator
  • String

The length of time that the cardholder has had the account with the 3DS Requestor.
Length: 2 characters

  • Account Change
  • String

The date that the cardholder’s account with the 3DS Requestor was last changed, including billing or shipping address, new payment account, or new user(s) added.
Length: 8 characters

Account ID
String
optional

Additional information about the account optionally provided by the 3DS Requestor.
Length: <= 64 characters

Billing Address City
String
optional

The city of the cardholder's billing address associated with the card used for this purchase.
Length: <= 50 characters

Billing Address Country
String
optional

The country of the cardholder's billing address associated with the card used for this purchase.
Length: 3 characters

Billing Address Line 1
String
optional

The first line of the cardholder's billing address associated with the card used for this purchase.
Length: <= 50 characters

Billing Address Line 2
String
optional

The second line of the cardholder's billing address associated with the card used for this purchase.
Length: <= 50 characters

Billing Address Line 3
String
optional

The third line of the cardholder's billing address associated with the card used for this purchase.
Length: <= 50 characters

Billing Address Postcode
String
optional

The ZIP or postal code of the cardholder's billing address associated with the card used for this purchase.
Length: <= 16 characters

Billing Address State
String
optional

The state or province of the cardholder's billing address associated with the card used for this purchase.
Length: <= 3 characters

Email Address
String
optional

The email address associated with the account that is either entered by the cardholder, or is on file with the 3DS Requestor.

Home Phone
Object
optional

The home phone number provided by the cardholder.

  • cc
  • String

The country code
Length: 1 to 3 characters

  • subscriber
  • String

The subscriber
Length: <= 15 characters

Mobile Phone
Object
optional

The mobile phone number provided by the cardholder.

  • cc
  • String

The country code
Length: <= 1 to 3 characters

  • subscriber
  • String

The subscriber
Length: <= 15 characters

Cardholder Name
String
optional

The cardholder's name.
Length: 2 to 45 characters

Shipping Address City
String
optional

The city of the cardholder's shipping address.
Length: <= 50 characters

Shipping Address Country
String
optional

The country of the cardholder's shipping address.
Length: 3 characters

Shipping Address Line 1
String
optional

The first line of the cardholder's shipping address.
Length: <= 50 characters

Shipping Address Line 2
String
optional

The second line of the cardholder's shipping address.
Length: <= 50 characters

Shipping Address Line 3
String
optional

The third line of the cardholder's shipping address.
Length: <= 50 characters

Shipping Address Postcode
String
optional

The ZIP or postal code of the cardholder's shipping address.
Length: 16 characters

Shipping Address State
String
optional

The state or province of the shipping address associated with the card being used for this purchase.
Length: <= 3 characters

Work Phone
Object
optional

The cardholder's work phone number.

  • Country Code
  • String

The country code
Length: 1 to 3 characters

  • Subscriber
  • String

The subscriber
Length: <= 15 characters

Device Information
Object
optional

Device information gathered by the 3DS SDK from a consumer device. This comprises JSON name-value pairs that, as a whole, are Base64url encoded. This will be populated by the DS as unencrypted data to the ACS obtained from SDK encrypted data.

Device Render Options
Object
optional

Defines the SDK user interface (UI) types that the device supports for displaying specific challenge UIs within the SDK.

  • SDK Interface
  • String

Lists all of the SDK interface types that the device supports for displaying specific challenge UIs within the SDK.
Length: 2 characters

  • SDK UI Type
  • Array

Lists all UI types that the device supports for displaying specific challenge UIs within the SDK.

Payment Token Indicator
Boolean
optional

A value of true indicates that the transaction was de-tokenized prior to being received by the ACS. This data element will be populated by the system residing in the 3DS domain where the de-tokenisation occurs (i.e., the 3DS Server or the DS).

Purchase Installment Date
String
optional

Indicates the maximum number of authorizations permitted for instalment payments.
Length: <= 3 characters

Merchant Risk Indicator
String
optional

The merchant's assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.

  • Delivery Email Address
  • String

For electronic delivery, the email address to which the merchandise was delivered.
Length: <= 245 characters

  • Delivery Timeframe
  • String

Indicates the delivery timeframe of the merchandise.
Length: 2 characters

  • Gift Card Amount
  • String

For prepaid or gift card purchase, the purchase amount total of prepaid or gift cards in major units (e.g., USD 123.45 is 123).
Length: 15 characters

  • Gift Card Count
  • String

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
Length: 2 characters

  • Gift Card Currency
  • String

For prepaid or gift card purchase, the currency code of the card.
Length: 3 characters

  • Pre Order Date
  • String

For a pre-ordered purchase, the expected date that the merchandise will be available.
Length: 8 characters

  • Pre Order Purchase Indicator
  • String

Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.
Length: 2 characters

  • Re Order Items Indicator
  • String

Indicates whether the cardholder is reordering previously purchased merchandise.
Length: 2 characters

Message Category
String
optional

Identifies the category of the message for a specific use case.
Length: 2 characters

Message Extension
Array
optional

An array containing the content of the extension.

  • Name
  • String

The name of the extension data set as defined by the extension owner.

  • ID
  • String

A unique identifier for the extension.
Payment System Registered Application Provider Identifier (RID) is required as a prefix of the ID.

  • Criticality Indicator
  • Boolean

A boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.

  • Data
  • Object

The data carried in the extension.

Notification URL
String
optional

Fully qualified URL of the system that receives the challenge response (CRes) message or error message. The CRes message is posted by the ACS through the cardholder's browser at the end of the challenge and receipt of the results response (RRes) message.
Length: <= 256 characters

Recurring Expiry
String
optional

Date after which no further authorizations shall be performed.
Length: 8 characters

Recurring Frequency
String
optional

Indicates the minimum number of days between authorizations.
Length: <= 4 characters

Response data elements

The following data elements may be included in the payment response.

Parameter
Description

Three DS Server Transaction ID
String

The unique ID for the payment request.

ACS Transaction ID
String

The universally unique transaction identifier assigned by the ACS to this transaction.

ACS Rendering Type
String

Identifies the ACS user interface template that the ACS will present to the customer.
Required for app-based transactions.

DS Transaction ID
String

The universally unique identifier assigned by the DS to this transaction.

Interaction Counter
Integer

Indicates the number of authentication cycles attempted by the cardholder. The value is tracked by the ACS.

Message Category
String

Identifies the category of the message for a specific use case.

Message Type
String

Identifies the type of message that is passed.

Message Version
String

The protocol version identifier. This is the protocol version number of the specification utilised by the system creating this message. The message version number is set by the 3DS Server which originates the protocol with the AReq message. This number does not change during a 3DS transaction.

Transaction Status
String

Indicates whether the transaction qualifies as an authenticated transaction or an account verification.

Transaction Status Reason
String

Indicates the reason for the transaction status.

Can we help?

Thanks for using Checkout.com. If you need any help or just have a question, please contact our support team at support@checkout.com.

3D Secure 2.0 data elements


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.