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`Stringrequired	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`Stringoptional	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 [email protected].