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.

ParameterDescription

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.

Up to 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.

Up to eight characters.

Browser Colour Depth

STRING

REQUIRED

A value representing the bit depth, in bits per pixel, of the color palette for displaying images. Obtained from the cardholder's browser using the screen.colorDepth property.

Up to two 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.

Up to six 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.

Up to six characters.

Browser Time Zone

STRING

REQUIRED

The time difference, in minutes, between UTC time and the local time of the cardholder's browser.

Up to five 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.

Up to one character.

Device Channel

STRING

REQUIRED

Indicates the type of device being used to initiate the transaction.

Up to two 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.

Up to 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.

Up to 256 characters.

SDK Max Timeout

STRING

REQUIRED

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

Up to two 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.

Up to 32 characters.

SDK Transaction ID

STRING

REQUIRED

Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

Up to 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.

ParameterDescription

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.

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

Two characters.

3DS Request Prior Authentication Timestamp

STRING

Date and time in UTC of the prior cardholder authentication.

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.

Up to 36 characters.

Account Type

STRING

OPTIONAL

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

Two characters.

Address Match

STRING

OPTIONAL

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

Broad Information

STRING

OPTIONAL

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

Card Expiry Date

STRING

OPTIONAL

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

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

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

Eight characters.

Account ID

STRING

OPTIONAL

Additional information about the account optionally provided by the 3DS Requestor.

Up to 64 characters.

Billing Address City

STRING

OPTIONAL

The city of the cardholder's billing address associated with the card used for this purchase.

Up to 50 characters.

Billing Address Country

STRING

OPTIONAL

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

Three characters.

Billing Address Line 1

STRING

OPTIONAL

The first line of the cardholder's billing address associated with the card used for this purchase.

Up to 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.

Up to 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.

Up to 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.

Up to 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.

Up to three 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.

Up to three characters.

subscriber

STRING

The subscriber.

Up to 15 characters.

Mobile Phone

OBJECT

OPTIONAL

The mobile phone number provided by the cardholder.

cc

STRING

The country code.

Up to three characters.

subscriber

STRING

The subscriber.

Up to 15 characters.

Cardholder Name

STRING

OPTIONAL

The cardholder's name.

Two to 45 characters.

Shipping Address City

STRING

OPTIONAL

The city of the cardholder's shipping address.

Up to 50 characters.

Shipping Address Country

STRING

OPTIONAL

The country of the cardholder's shipping address.

Three characters.

Shipping Address Line 1

STRING

OPTIONAL

The first line of the cardholder's shipping address.

Up to 50 characters.

Shipping Address Line 2

STRING

OPTIONAL

The second line of the cardholder's shipping address.

Up to 50 characters.

Shipping Address Line 3

STRING

OPTIONAL

The third line of the cardholder's shipping address.

Up to 50 characters.

Shipping Address Postcode

STRING

OPTIONAL

The ZIP or postal code of the cardholder's shipping address.

Up to 16 characters.

Shipping Address State

STRING

OPTIONAL

The state or province of the shipping address associated with the card being used for this purchase.

Up to three characters.

Work Phone

OBJECT

OPTIONAL

The cardholder's work phone number.

Country Code

STRING

The country code.

Up to three characters.

Subscriber

STRING

The subscriber.

Up to 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.

Two 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-tokenization occurs (i.e., the 3DS Server or the DS).

Purchase Installment Date

STRING

OPTIONAL

Indicates the maximum number of authorizations permitted for instalment payments.

Up to three 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.

Up to 245 characters.

Delivery Timeframe

STRING

Indicates the delivery timeframe of the merchandise.

Two characters.

Gift Card Amount

STRING

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

Up to 15 characters.

Gift Card Count

STRING

For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased.

Two characters.

Gift Card Currency

STRING

For prepaid or gift card purchases, the currency code of the card.

Three characters.

Pre Order Date

STRING

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

Eight characters.

Pre Order Purchase Indicator

STRING

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

Two characters.

Re Order Items Indicator

STRING

Indicates whether the cardholder is reordering previously purchased merchandise.

Two characters.

Message Category

STRING

OPTIONAL

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

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

Up to 256 characters.

Recurring Expiry

STRING

OPTIONAL

Date after which no further authorizations shall be performed.

Eight characters.

Recurring Frequency

STRING

OPTIONAL

Indicates the minimum number of days between authorizations.

Up to four characters.

Response data elements

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

ParameterDescription

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

STRING

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 help or have a question, message our Support team at support@checkout.com.