3D Secure Parameters

To successfully process 3D Secure transactions, it is important to send all the necessary parameters. Below you can find information about the mandatory, conditional and optional fields both in the request and response messages.

Even though a lot of request parameters are optional, please note that in order to have a better rate of successful risk-checks during the risk based authentication it is recommended to send as many fields as possible. This will positively affect the number of frictionless flows.

For more information about the request and response fields, please refer to our API reference guide.

Request parameters

Basic payment data

Field name Mandatory/Optional Format, Length
card.holder Required unless market or regional mandate restricts sending this information. Length: Variable, 2 - 45 characters
Format: String
card.expiryMonth Mandatory Length: 2 characters
Format: numeric
card.expiryYear Mandatory Length: 4 characters
Format: numeric
card.number Mandatory Length: Variable, 13-19
Format: numeric
amount Mandatory Length: Variable, maximum 12 characters
Format: Numeric with 2 minor units after the decimal point
Example: 123.00
currency Mandatory Length: 3 characters
Format: ISO 4217 A3 currency code

Browser data

Field name Mandatory/Optional Format, Length
customer.browser.acceptHeader Mandatory Length: Variable, maximum 2048 characters
Format: String
customer.browser.language Mandatory Length: Variable, 1–8 characters
Format: String
Returned from navigator.language property.
customer.browser.screenHeight Mandatory Length: Variable, 1–6
Format: Numeric
Value is returned from the screen.height property
customer.browser.screenWidth Mandatory Length: Variable, 1–6
Format: Numeric
Value is returned from the screen.width property
customer.browser.timezone Mandatory Length: Variable, 1–5 characters
Format: Numeric
Value is returned from the getTimezoneOffset() method.
customer.browser.userAgent Mandatory Length: Variable, maximum 2048 characters
Format: String
customer.ip Required unless market or regional mandate restricts sending this information. Length: Variable, maximum 45 characters
Format: IPv4 address
Example: 1.12.123.255
customer.browser.javaEnabled Mandatory when customer.browser.javascriptEnabled = true; otherwise Optional Values accepted:
• true
• false
Value is returned from the navigator.javaEnabled property.
customer.browser.javascriptEnabled Mandatory Values accepted:
• true
• false
customer.browser.screenColorDepth Optional Length: 1–2 characters
Format: String
Values accepted:
• 1 = 1 bit
• 4 = 4 bits
• 8 = 8 bits
• 15 = 15 bits
• 16 = 16 bits
• 24 = 24 bits
• 32 = 32 bits
• 48 = 48 bits
customer.browser.challengeWindow Optional Length: 2 characters
Values accepted:
• 01 = 250 x 400
• 02 = 390 x 400
• 03 = 500 x 600
• 04 = 600 x 400
• 05 = Full screen

Customer and address details

Field name Mandatory/Optional Format, Length
customer.email Required unless market or regional mandate restricts sending this information. Length: Variable, maximum 128 characters
Format: String
customer.phone One of customer.phone/customer.workPhone/customer.mobile must be provided Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc - country code, maximum 3 characters
"-" - mandatory character
nnnnnnnnnn - phone number without the country code, maximum 15 characters
customer.workPhone One of customer.phone/customer.workPhone/customer.mobile must be provided Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc - country code, maximum 3 characters
"-" - mandatory character
nnnnnnnnnn - phone number without the country code, maximum 15 characters
customer.mobile One of customer.phone/customer.workPhone/customer.mobile must be provided Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc - country code, maximum 3 characters
"-" - mandatory character
nnnnnnnnnn - phone number without the country code, maximum 15 characters
billing.city Required unless market or regional mandate restricts sending this information. Length: Variable, 2–45 characters
Format: String
billing.country Required unless market or regional mandate restricts sending this information. Length: 2 characters
Format: ISO 3166-1 A2 country code
billing.street1 Required unless market or regional mandate restricts sending this information. Length: Variable, maximum 50 characters
Format: String
billing.street2 Optional Length: Variable, maximum 50 characters
Format: String
billing.postcode Required unless market or regional mandate restricts sending this information. Length: Variable, maximum 50 characters
Format: String
billing.state Optional Length: Variable: maximum 3 characters
Format: Should be the country subdivision code defined in ISO 3166-2
shipping.city Optional Length: Variable, maximum 50 characters
Format: String
shipping.country Optional Length: 2 characters
Format: ISO 3166-1 A2 country code
shipping.street1 Optional Length: Variable, maximum 50 characters
Format: String
shipping.street2 Optional Length: Variable, maximum 50 characters
Format: String
shipping.postcode Optional Length: Variable, maximum 16 characters
Format: String
shipping.state Optional Length: Variable: maximum 3 characters
Format: Should be the country subdivision code defined in ISO 3166-2

3D Secure specific data

Field name Mandatory/Optional Format, Length
threeDSecure.amount Optional Length: Variable, maximum 12 characters
Format: Numeric with 2 minor units after the decimal point
Example: 123.00
threeDSecure.currency Optional Length: 3 characters
Format: ISO 4217 A3 currency code
threeDSecure.challengeIndicator Optional Length: 2 characters
Format: Refer to the table below
threeDSecure.exemptionFlag Optional Length: 2 characters
Format: Please follow our exemption management guide

Authentication amount and currency

In some cases the amount and/or currency that is used in the authentication can be different from the one that will be used in the payment later. For example the payment amount might not be known at the time of the authentication, or the merchant would like to authenticate the shopper for the full amount when the payment will be done in multiple installments.

If the authentication amount and the payment amount are different, then the authentication amount and currency can be sent in a separate field:

threeDSecure.amount Amount for which the shopper will be authenticated for.
threeDSecure.currency Currency for which the shopper will be authenticated for.

Please note that payment amount and currency are still mandatory fields for any payment request. If there are no authentication amount and currency defined then the shopper will be authenticated with the payment amount and currency.

3DS Challenge Indicator and MIT agreements

The merchants have the possibility to set the preference of a transaction being challenged or not. This is only a preference, and won't guarantee that the issuer will or will not request a challenge from the cardholder. It is up to the issuer to consider the merchant's preference during the risk assessment of the transaction. As an example, regional mandates might require transactions to be challenged and the merchant should ask for a mandated challenge. Thus the merchants have the option to send the field threeDSecure.challengeIndicator with one of the following values: Send the field threeDSecure.challengeIndicator with one of the following values:

Value Challenge Preference Description
01 No preference The merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02 No challenge requested The merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03 Challenge requested: 3D Secure Requestor Preference The merchant prefers that the cardholder is authenticated by the issuer.
04 Challenge requested: Mandate The cardholder authentication is mandated (eg. by regional mandates)
Note: Merchants performing recurring payments are required to have a merchant-initiated transaction (MIT) agreement with the cardholder. This grants the merchant permission to store the cardholder's card data for future transactions when the cardholder is not present. The following requirements apply to these MIT agreements:
  • MIT agreements must have an originating cardholder-initiated transaction (CIT).
  • The initial CIT payment request must go through strong customer authentication (SCA).
  • Scheme regulations mandate that merchants must populate threeDSecure.challengeIndicator with value 04 when sending the initial CIT; this forces the issuer to apply SCA.
  • If these requirements are not met, merchants are likely to experience payment failures for future MIT requests as a result of SCA not being applied.
05 No challenge requested Transactional risk analysis is already performed
06 No challenge requested Data share only
07 No challenge requested Strong consumer authentication is already performed
08 No challenge requested Utilize whitelist exemption if no challenge required
09 Challenge requested Whitelist prompt requested if challenge required

Note: For initial 3DS 2 CIT payment requests and any 3DS 2 transactions with field createRegistration set to true, field ChallengeIndicator will be populated a default value of "04 - Challenge Requested Mandate". This default value will only be populated if the merchant has not populated this field themselves; any merchant-provided values will not be overridden.


Information about the cardholder's account and history with the merchant

The following fields are not mandatory, but it is strongly recommended to send them. They are affecting the accuracy of the issuer's risk check, and will result in more frictionless flows.

The field values below can be collected by the 3D Secure Requestor* about the cardholders activity on their webshop.

*3D Secure Requestor denotes the merchant

Field name Description
customParameters[ReqAuthMethod]

Method used by the Cardholder to authenticate to the 3D Secure Requestor.

Contains optional information about how the cardholder authenticated during login to their 3D Secure Requestor account.

Possible values are:

01 No authentication occurred (i.e. cardholder "logged in" as guest)
02 Login to the cardholder account at the merchant system using cardholder's own credentials
03 Login to the cardholder account at the merchant system using federated ID
04 Login to the cardholder account at the merchant system using issuer credentials
05 Login to the cardholder account at the merchant system using third-party authentication
06 Login to the cardholder account at the merchant system using FIDO Authenticator
customParameters[ReqAuthTimestamp]

Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Part of the 3D Secure Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their account.

customParameters[PriorAuthMethod]

Mechanism used by the Cardholder to previously authenticate to the 3D Secure Requestor.

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

Possible values are:

01 Frictionless authentication occurred by ACS
02 Cardholder challenge occurred by ACS
03 ACS verified
04 Other issuer methods
customParameters[PriorAuthTimestamp]

Date and time in UTC of the prior cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameters[PriorReference]

This data element provides additional information to the ACS to determine the best approach for handling a request. It contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameters[PriorAuthData]

This data element contains DS Transaction ID for a prior authenticated transaction as a part of a 3DS Requestor Initiated (3RI) transaction and an AAV Refresh transaction. This parameter helps to improve the ACS chances of approving the transaction linked to a previously authenticated transaction. An AAV Refresh transaction in 3DS 2.1 request must populate the DS Transaction ID of the original authentication transaction that is being refreshed.

Format of the 3DS Requestor Prior Transaction Authentication Data is defined in a JSON Data Type: String. Example: customParameters[PriorAuthData]=dsTransID: 9aed2dc3-4473-4bb8-a763-7bac4b40de3a. It allows up to 2048 characters. Incorrectly formatting could result in processing error.

customParameters[AAVRefresh]

Mastercard generates an Account holder Authentication Values (AAV) for every successfully authenticated payment transaction since 3DS 2.1. Mastercard retention and validity period for an AAV is 10-90 days. AAV Refresh capability allows merchants to request a ‘refreshed’ AAV using a non-payment (NPA) request from the issuer ACS for their previously fully authenticated transaction. Send DS Transaction ID of previously authenticated transaction in customParameters[PriorAuthData].

Possible values: true/false

customParameters[AccountId] Additional information about the account optionally provided by the 3D Secure Requestor in AReq messages.
customParameters[AccountAgeIndicator]

Length of time that the cardholder has had the account with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameters[AccountChangeDate] Date that the cardholder's account with the 3D Secure Requestor was last changed. Accepted date format is YYYYMMDD.
customParameters[AccountChangeIndicator]

Length of time since the cardholder's account information with the 3D Secure Requestor was last changed.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameters[AccountDate] Date that the cardholder opened the account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameters[AccountPasswordChangeDate] Date that cardholder's account with the 3D Secure Requestor had a password change or account reset. Accepted date format is YYYYMMDD.
customParameters[AccountPasswordChangeIndicator] Indicates the length of time since the cardholder's account with the 3D Secure Requestor had a password change or account reset.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameters[AccountPurchaseCount] Number of purchases with this cardholder account during the previous six months.
customParameters[AccountProvisioningAttempts] Number of Add Card attempts for the account in the last 24 hours.
customParameters[AccountDayTransactions] Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all payment accounts in the previous 24 hours.
customParameters[AccountYearTransactions] Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all payment accounts in the previous year.
customParameters[PaymentAccountAge] Date that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameters[PaymentAccountAgeIndicator]

Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameters[ShipAddressUsageDate] Date when the shipping address used for this transaction was first used with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameters[ShipAddressUsageIndicator]

Indicates the length of time since the shipping address used for this transaction was first used with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameters[ShipIndicator]

Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not their general business. If one or more items are included in the sale, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item.

Possible values are:

01 Ship to cardholder's billing address
02 Ship to another verified address on file with merchant
03 Ship to address that is different than the cardholder's billing address
04 "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields)
05 Digital goods (includes online services, electronic gift cards and redemption codes)
06 Travel and Event tickets, not shipped
07 Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
customParameters[ShipNameIndicator]

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

Possible values are:

01 Account Name identical to shipping Name
02 Account Name different than shipping Name
customParameters[SuspiciousAccountActivity]

Indicates whether the 3D Secure Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Possible values are:

01 No suspicious activity has been observed
02 Suspicious activity has been observed
customParameters[TransactionType]

Identifies the type of transaction being authenticated.

Possible values are:

01 Goods / Service Purchase
03 Check Acceptance
10 Account Funding
11 Quasi-Cash Transaction
28 Prepaid Activation and Load
customParameters[DeliveryTimeframe]

Indicates the merchandise delivery timeframe.

Possible values are:

01 Electronic Delivery
02 Same Day Shipping
03 Overnight Shipping
04 Two-day or more shipping
customParameters[DeliveryEmailAddress]

For Electronic delivery, the email address to which the merchandise was delivered.

customParameters[ReorderItemsIndicator]

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

01 First time ordered
02 Reordered
customParameters[PreOrderPurchaseIndicator]

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

Possible values are:

01 Merchandise available
02 Future availability
customParameters[PreOrderDate]

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

customParameters[GiftCardAmount]

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

customParameters[GiftCardCurrency]

For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.

customParameters[GiftCardCount]

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

Response parameters

In the returned response there are two places where 3D Secure related response values can be present. In the "threeDSecure" object we store the values that are not brand specific and can be returned by any card brand and issuer. In the "resultDetails" object we store the brand specific values if the scheme directory server returns such value.

Values returned in the threeDSecure object

Value Description
eci Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.
verificationId Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.
version Version of the 3D Secure that was used for authentication
flow Indicates the user flow that was applied during the authentication: challenge or frictionless
dsTransactionId Universally unique transaction identifier assigned by the DS to identify a single transaction.
challengeMandatedIndicator Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.
authenticationType Authentication approach that the ACS used to authenticate the Cardholder for this specific transaction.
acsTransactionId This field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction.
cardHolderInfo Information text provided by the ACS/Issuer to the cardholder. Contains useful information, especially in case of a transaction decline.
errorCode Returned in case of an error. Code indicating the type of problem identified in the message.
errorDescription Returned in case of an error. Describes the problem identified in the message.
errorSource Returned in case of an error. Indicates the component causing the issue.
Example
"threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.2.0",
    "flow":"challenge"
    "dsTransactionId":"1231-2342-3453-4564",
    "challengeMandatedIndicator":"Y",
    "authType":"2",
    "acsTransactionId":"7777-8797-4645-1233"
  },

Example (error case)
"threeDSecure":{
    "version":"2.2.0",
    "errorCode":"101",
    "errorDescription":"MerchantCategoryCode must be specified.",
    "errorSource":"3DS Server"
  },

Values returned in the resultDetails object

Value Returned for brand Description
CB_Authentication_value_algorithm Cartes Bancaires Identifies the algorithm used by the ACS to calculate the Authentication Value. For example: 0 = HMAC (per SET stain); 1 = CVV; 2 = CVV with ATN; 3 = SPA AAC; A = AV-CB
CB_Score Cartes Bancaires Global score calculated by the Cartes Bancaires Scoring platform
Example
"resultDetails":{
    "ExtendedDescription":"Approved or completed successfully",
    "clearingInstituteName":"Clearing_Institute",
    "ConnectorTxID1":"12345",
    "AcquirerResponse":"00",
    "reconciliationId":"132499881"
    "CB_Authentication_value_algorithm":"2"
    "CB_Score":"55"
  },

Result codes

Please refer to our reference guide for information about the possible result codes.