Parameters

3DS version 2.0 supports much more input parameters than the previous version 1.0. Most of these parameters will be used by the card issuing bank to evaluate the risk of the payment transaction.

Even if most of the parameters are optional, some are recommended to increase the chance of a frictionless flow and to bypass a challenge for the cardholder.

The following sections and tables list all parameters relevant for the 3DS 2.0 authentication.

More technical details on an API service level can be found in our API documentation.

Input Parameter

Parameter	Required	Description
cardholderName	optional	The name of the cardholder.
email	optional	The email address of the cardholder.
billingAddress	optional	object containing the shipping address details.
billingAddress.street	optional	The street address of the cardholder billing address.
billingAddress.houseNumber	optional	The street number of the cardholder billing address.
billingAddress.city	optional	The city of the cardholder billing address.
billingAddress.zip	optional	The postal code of the cardholder billing address.
billingAddress.state	optional	The state of the cardholder billing address.
billingAddress.country	optional	The country of the cardholder billing address.
shippingAddress	optional	Object containing the shipping address details.
shippingAddress.street	optional	The street address of the shipping address requested by the cardholder.
shippingAddress.houseNumber	optional	The street number of the shipping address requested by the cardholder.
shippingAddress.city	optional	The city of the shipping address requested by the cardholder.
shippingAddress.zip	optional	The postal code of the shipping address requested by the cardholder.
shippingAddress.state	optional	The state of the shipping address requested by the cardholder.
shippingAddress.country	optional	The country of the shipping address requested by the cardholder.

Transaction Data

Parameter	Required	Description
amount	required	The amount of the purchase. In case of an authentication without payment for recurring future payments this should include the expected total purchase amount.
currency	required	The currency of the purchase.
recurringExpiry	conditional	Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.
recurringFrequency	conditional	Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

Risk Data

Parameter	Required	Description
customerAccount	optional	An object containing information about the customer account with the merchant.
customerAccount.accountIdentifier	optional	The account identifier at the merchant side.
customerAccount.creationDate	optional	The date when the customer opened the account with the merchant.
customerAccount.lastChangeDate	optional	The date when the customer account with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.
customerAccount.changeIndicator	optional	Length of the time since the customer account information with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added. Supported values: CHANGED_WITH_THIS_TRANSACTION / LESS_THAN_THIRTY_DAYS / THIRTY_TO_SIXTY_DAYS / MORE_THAN_SIXTY_DAYS
customerAccount.lastPasswordChangeDate	optional	The date when the customer account with the merchant had a password change or account reset.
customerAccount.passwordChangeIndicator	optional	Length of the time since the customer account information with the merchant had a password change or account reset. Supported values: NO_CHANGE / CHANGED_WITH_THIS_TRANSACTION / LESS_THAN_THIRTY_DAYS / THIRTY_TO_SIXTY_DAYS / MORE_THAN_SIXTY_DAYS
customerAccount.authenticationMethod	optional	Mechanism used by the customer to authenticate to the merchant account. Supported values: GUEST / OWN_CREDENTIALS / FEDERATED_ID / ISSUER_CREDENTIALS / THIRD_PARTY_AUTH / FIDO_AUTHENTICATOR
customerAccount.authenticationTimestamp	optional	Date and time in UTC of the customer authentication to the merchant account.
customerAccount.shippingAddressUsageIndicator	optional	Indicates when the shipping address used for this transaction was first used with the merchant account. Supported values: FIRST_TIME / LESS_THAN_THIRTY_DAYS / THIRTY_TO_SIXTY_DAYS / MORE_THAN_SIXTY_DAYS
customerAccount.shippingAddressFirstUsage	optional	Date when the shipping address used for this transaction was first used with the merchant.
customerAccount.transactionCountLastDay	optional	Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.
customerAccount.transactionCountLastYear	optional	Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.
customerAccount.orderCountLast6Months	optional	Number of purchases with this cardholder account during the previous six months.
customerAccount.suspiciousActivity	optional	Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.
customerAccount.accountEqualsShippingName	optional	Indicates if the customer name on the account is identical to the shipping name used for this transaction.
customerAccount.paymentAccountAgeIndicator	optional	Indicates the length of time that the payment account was enrolled in the customer account with the merchant. Supported values: NO_ACCOUNT / CREATED_WITH_THIS_TRANSACTION / LESS_THAN_THIRTY_DAYS / THIRTY_TO_SIXTY_DAYS / MORE_THAN_SIXTY_DAYS /
customerAccount.paymentAccountEnrollementDate	optional	Date that the payment account was enrolled in the customer account with the merchant. Date format must be YYYYMMDD.
shippingInfo	optional	object containing information about the shipping details for this transaction.
shippingInfo.shippingEqualsBillingAddress	optional	Flag if the shipping address equals the billing address.
shippingInfo.shippingIndicator	optional	Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator that most accurately describes the customer's specific transaction. If one or more items are included in the sale, use the shipping indicator for the physical goods, or if all digital goods, use the indicator that describes the most expensive item. Supported values: SHIP_TO_BILLING_ADDRESS / SHIP_TO_VERIFIED_ADDRESS / SHIP_TO_DIFFERENT_ADDRESS / SHIP_TO_STORE / DIGITAL_GOODS / TICKETS_NOT_SHIPPED / OTHER
shippingInfo.deliveryTime	optional	Indicates the merchandise delivery timeframe. Supported values: ELECTRONIC / SAME_DAY / OVERNIGHT / TWO_DAY_OR_MORE
shippingInfo.deliveryEmail	optional	For electronic delivery, the email address to which the merchandise was delivered.
orderInfo	optional	object containing order information relevant for risk evaluation
orderInfo.isReorder	optional	Indicates whether the cardholder is reordering previously purchased merchandise.
orderInfo.preOrderIndicator	optional	Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. Supported values: MERCHANTDISE_AVAILABLE / FUTURE_AVAILABILITY
orderInfo.preOrderDate	optional	For a pre-ordered purchase, the expected date that the merchandise will be available.
orderInfo.orderType	optional	Identifies the type of transaction being authenticated. The values are derived from ISO 8583. Supported values: 01 -> Goods / Service purchase / 03 -> Check Acceptance / 10 -> Account Funding / 11 -> Quasi-Cash Transaction / 28 -> Prepaid activation and Loan

Browser Data

Parameter	Required	Description
acceptHeader	required	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder's browser. This field is limited to maximum 2048 characters and if the total length exceeds the limit, the 3DS Server truncates the excess portion.
ip	optional	IP address of the browser as returned by the HTTP headers to the 3DS Requestor. The field is limited to maximum 45 characters and the accepted values are as following: IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255.
javaEnabled	required	Boolean that represents the ability of the cardholder browser to execute Java.
language	required	Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property.
colorDepth	required	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. The field is limited to 1-2 characters.
screenHeight	required	Total height of the cardholder's screen in pixels. Value is returned from the screen.height property. The value is limited to 1-6 characters.
screenWidth	required	Total width of the cardholder's screen in pixels. Value is returned from the screen.width property. The value is limited to 1-6 characters.
timezone	required	Time difference between UTC time and the cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method.
userAgent	required	Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
challengeWindowSize	required	Dimensions of the challenge iFrame window that should be displayed to the cardholder in case of a challenge. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width X height in pixels of the window displayed in the cardholder browser window. This is used only to prepare the CReq request and it is not part of the AReq flow. If not present it will be omitted. However, when sending the challenge request accepted values are: 01 -> 250 x 400 / 02 -> 390 x 400 / 03 -> 500 x 600 / 04 -> 600 x 400 / 05 -> Full screen

Output Parameter

The following parameters are relevant for a 3DS 2.0 authentication response.

Authentication Result

Parameter	Required	Description
version	required	The version of the 3DS protocol. Supported values: 1.0, 2.0
status	required	The email address of the cardholder. Indicates whether a transaction qualifies as an authenticated transaction. Y = authentication verification successful / A = authentication attempted; not authenticated, but a proof of attempted authentication is provided / C = challenge required; additional SCA authentication is required / R = authentication rejected; issuer is rejecting / N = not authenticated; transaction denied. / U = authentication could not be performed; technical or other problem
transactionId	required	The transaction identifier from the 3DS authentication. 3DS 1.0: This will be the XID / 3DS 2.0: This will be the dsTransID
authenticationValue	optional	The authenticationValue returned in the 3DS authentication. CAVV: Visa, AMEX, JCB, Diners/Discover / UCAF: Mastercard
eci	optional	The Electronic Commerce Indicator (ECI) provided by the ACS or DS to indicate the results of the attempt to authenticate the cardholder. The ECI values might differ depending on the card scheme. For all fully authenticated or authentication attempted transactions the liability will be shifted to the card issuer. Mastercard: 00 - no authentication available / 01 - authentication attempted / 02 - fully authenticated / 07 - fully authenticated (Mastercard distinguishes between fully authenticated recurring payments (flagged with ECI 07) and all other fully authenticated transactions (flagged with ECI 02)) All other card schemes: 05 - fully authenticated / 06 - authentication attempted / 07 - no authentication available
challengeData	conditional	Object containing details for the challenge iFrame in case the status=C. Only relevant for 3DS 2.0
challengeData.acsUrl	required	Fully qualified URL of the ACS in case the authentication response message indicates that further cardholder interaction is required to complete the authentication.
challengeData.base64EncodedChallengeRequest	required	Base64-encoded challenge request object in case the authentication response message indicates that further cardholder interaction is required to complete the authentication.
challengeData.challengeWindowSize	required	Dimensions of the challenge iframe window in which the challenge page will be displayed to the Cardholder. This value should match the provided size in the browserInfo call. EMVCo assigned window size. '01' -> 250px x 400px, '02' -> 390px x 400px, '03' -> 500px x 600px, '04' -> 600px x 400px, '05' -> Full screen, or full container content

Parameters

Parameters

Input Parameter

Transaction Data

Risk Data

Browser Data

Output Parameter

Authentication Result

What was your feeling about it?