3-D Secure V2 parameters
1. Introduction
This list contains all relevant 3-D Secure V2 parameters. It is split up in three sections:
2. Mandatory parameters
If you are processing transactions via DirectLink, you must to add these parameters to your request.
| Parameter |
Description | Format | |
|---|---|---|---|
| browserAcceptHeader |
Browser Accept Headers. Exact content of the HTTP accept headers as sent to the merchant from the Cardholder’s browser. Length: Variable, maximum 2048 characters |
Length: Variable, maximum 2048 characters |
|
| browserColorDepth |
Browser Color Depth. Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen color Depth property. Please note – The possible values are defined by the 3DSecure v2 specification. There may be browsers that have a colour depth that is not one of these permitted values. In such instances, we would encourage you to send the next accepted value (e.g. if color depth is 30 bits, send a value of 24). |
Data Type: String |
|
| browserJavaEnabled |
Browser Java Enabled. Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator java Enabled property. |
Data Type: Boolean |
|
| browserLanguage |
Browser Language. Value representing the browser language as defined in IETF BCP47. Returned from navigator language property. (E.g. en, fr, en-US, fr-ca) It is not case-sensitive. |
Length: Variable, 1–8 characters xx, xxx, xx-XX or xx-xxxx-xx. |
|
| browserScreenHeight |
Browser Screen Height. Total height of the Cardholder’s screen in pixels. Value is returned from the screen height property. |
Data Type: Int |
|
| browserScreenWidth |
Browser Screen Width. Total width of the cardholder’s screen in pixels. Value is returned from the screen width property. |
Data Type: Int |
|
| browserTimeZone |
Browser Time Zone. Time difference between UTC time and the Cardholder browser local time, in minutes. |
Data Type: Int |
|
| browserUserAgent |
Browser User Agent. Exact content of the HTTP user-agent header. |
Length: Variable, maximum 2048 characters Data Type: String |
|
| ACCEPTURL |
URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised). (E.g. http://www.myshop.com/accept.html) |
AN Maximum 200 characters |
|
| DECLINEURL |
URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section). (E.g. http://www.myshop.com/decline.html) |
AN Maximum 200 characters |
|
| EXCEPTIONURL |
URL of the webpage to show the customer when the payment result is uncertain. (E.g. http://www.myshop.com/exception.html) |
AN Maximum 200 characters |
|
| LANGUAGE |
The payment page languages currently offered to the buyer (card holder / account holder), for example: “en_US” |
AN The format is "language_Country". Maximum 5 characters |
|
| FLAG3D |
Fixed value: ‘Y’ Instructs our system to perform 3-D Secure identification if necessary. |
AN Maximum 1 character |
|
| CN |
cardholderName
|
Length: Variable, maximum 35 characters |
If you process transactions for Visa, make sure to add the following mandatory parameters as well:
For all integration modes:
Mpi.WorkPhone.countryCode + Mpi.WorkPhone.subscriber
or
Mpi.MobilePhone.countryCode + Mpi.MobilePhone.subscriber
or
Mpi.HomePhone.countryCode + Mpi.HomePhone.subscriber
or
EMAIL
For DirectLink requests:
REMOTE_ADDR
3. Recommended parameters
The major card schemes highly recommend including these, as they will enhance the chance of a frictionless flow.
| Parameter |
Name / Description | Format | |
|---|---|---|---|
| ECOM_BILLTO_POSTAL_CITY |
billAddrCity Invoicing city |
Length: Variable, max 25 |
|
| ECOM_BILLTO_POSTAL_COUNTRYCODE |
billAddrCountry Invoicing country code |
Length max 2 |
|
| ECOM_BILLTO_POSTAL_STREET_LINE1 |
billAddrLine1 Billing address, first line
|
Length: Variable, max 60 |
|
| ECOM_BILLTO_POSTAL_STREET_LINE2 |
billAddrLine2 Billing address, second line |
Length: Variable, max 60 |
|
| ECOM_BILLTO_POSTAL_POSTALCODE |
billAddrPostCode Invoicing Postal Code |
Length: Variable, max 10 |
|
|
Customer’s email address |
Length: Variable, max 50 |
For Hosted Payment Page implementations, please also refer to the ePDQ Hosted Payment Page integration guide for the appropriate parameter requirements instead.
4. Optional parameters
In addition, you can send from these as many as you wish. The more parameters you send, the higher the chance of a frictionless flow.
| Parameter |
Name / Description | Format | |
|---|---|---|---|
| Mpi.threeDSRequestorChallengeIndicator |
Use this parameter to request exemptions of 3DS. Merchant Challenge Indicator. Indicates whether a challenge is requested for this transaction. For example: For 01-PA, a merchant may have concerns about the transaction, and request a challenge. For 02-NPA, a challenge maybe necessary when adding a new card to a wallet. For local/regional mandates or other variables. |
Length: 2 characters
|
|
| Mpi.merchantFraudRate |
Merchant Fraud Rate Merchant fraud rate in the EEA (all EEA card fraud divided by all EEA card volumes) calculated as per PSD2 Regulatory Technical Standards (RTS). Make sure to calculate the rate according to PSD2 RTS Article 19 regulation, as neither MasterCard nor we will validate the score. |
Length: max 2 characters
|
|
| Mpi.cardholderAccountChangeIndicator |
Cardholder Account Change Indicator. Length of time since the cardholder’s account information with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. |
Length: 2 characters
|
|
| Mpi.cardholderAccountDate |
Cardholder Account Date. Date that the cardholder opened the account with the merchant. |
Length: 8 characters Data Type: Date Format accepted: Date format = YYYYMMDD |
|
| Mpi.cardholderAccountPasswordChange |
Cardholder Account Password Change. Date that cardholder’s account with the merchant had a password change or account reset. |
Length: 8 characters Data Type: Date Format accepted: Date format = YYYYMMDD |
|
| Mpi.cardholderAccountPasswordChangeIndicator |
Cardholder Account Password Change Indicator. Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset. |
Length: 2 characters Data Type: String Values accepted: • 01 = No change • 02 = Changed during this transaction • 03 = Less than 30 days • 04 = 30−60 days • 05 = More than 60 days |
|
| Mpi.numberOfPurchaseWithAccountInTheLastSixMonths |
Cardholder Account Purchase Count. Number of purchases with this cardholder account during the previous six months. |
Data Type: Int Between 0 and 9999 |
|
| Mpi.paymentAccountAge |
Payment Account Age. Date that the payment account was enrolled in the cardholder’s account with the merchant. |
Length: 8 characters Data Type: Date Format accepted: Date format = YYYYMMDD |
|
| Mpi.paymentAccountAgeIndicator |
Payment Account Age Indicator. Indicates the length of time that the payment account was enrolled in the cardholder’s account with the merchant. |
Length: 2 characters |
|
| Mpi.provisionAttemptsInTheLast24Hours |
Number of Provisioning Attempts Day. Number of Add Card attempts in the last 24 hours. |
Data Type: Int Between 0 and 999 |
|
| Mpi.shippingAddressUsage |
Shipping Address Usage. Date when the shipping address used for this transaction was first used with the merchant. |
Length: 8 characters |
|
| Mpi.shippingAddressWasFirstUsed |
Shipping Address Usage Indicator. Indicates when the shipping address used for this transaction was first used with the merchant. |
Length: 2 characters Data Type: String Values accepted: • 01 = This transaction • 02 = Less than 30 days • 03 = 30−60 days • 04 = More than 60 day |
|
| Mpi.shippingNameAndCardholderNameAreIdentical |
Shipping Name Indicator. Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. |
Data Type: Boolean Values accepted:
|
|
| Mpi.suspiciousAccountActivityDetected |
Suspicious Account Activity. Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. |
Data Type: Boolean |
|
| Mpi.transactionActivityInTheLast24Hours |
Number of Transactions Day. Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous 24 hours. |
Data Type: Int Between 0 and 999 |
|
| Mpi.transactionActivityLastYear |
Number of Transactions Year. Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous year. |
Data Type: Int Between 0 and 999 |
|
| Mpi.challengeWindowSize |
Challenge Window Size. Dimensions of the challenge window that has been displayed to the Cardholder. 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. |
Length: 2 characters Data Type: String Value accepted: • 01 = 250 x 400 • 02 = 390 x 400 • 03 = 500 x 600 • 04 = 600 x 400 • 05 = Full screen If you don't send this parameter, then the default value will be 05 = Full screen. |
|
| Mpi.HomePhone.countryCode |
Home Phone Country Code. Country code of a home phone. |
Data Type: string Length: 3 characters ITU-E.164 country code |
|
| Mpi.HomePhone.subscriber |
Home Phone. Home phone (without country code) |
Data Type: string Length: 0 and 15 |
|
| Mpi.deliveryEmailAddress |
Delivery Email Address. For Electronic delivery, the email address to which the merchandise was delivered. |
Length: maximum 254 characters Data Type: String |
|
| Mpi.deliveryTimeframe |
Delivery Timeframe. Indicates the merchandise delivery timeframe. |
Length: 2 characters Data Type: String Values accepted: • 01 = Electronic Delivery • 02 = Same day shipping • 03 = Overnight shipping • 04 = Two-day or more shipping |
|
| Mpi.giftCardAmount |
Gift Card Amount. 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) |
Length: maximum 15 characters Data Type: Int Between 0 and 999999999999999 | |
| Mpi.giftCardCount |
Gift Card Count. For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. |
Data Type: Int Between 0 and 99 | |
| Mpi.giftCardCurrency |
Gift Card Currency. For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. |
Length: 3 characters Data Type: String |
|
| Mpi.preOrderDate |
Pre-Order Date. For a pre-ordered purchase, the expected date that the merchandise will be available |
Length: 8 characters Data Type: Date Format accepted: Date format = YYYYMMDD |
|
| Mpi.cardholderAccountAgeIndicator |
Cardholder Account Age Indicator: Length of time that the cardholder has had the account with the merchant. |
Length: 2 characters Data Type: String Values accepted: • 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 |
|
| Mpi.cardholderAccountChange |
Cardholder Account* Change. Date that the cardholder’s account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. |
Length: 8 characters Data Type: Date Format accepted: Date format = YYYYMMDD |
|
| Mpi.preOrderPurchaseIndicator | Pre-Order Purchase Indicator. Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. |
Length: 2 characters Data Type: String Values accepted: • 01 = Merchandise available • 02 = Future availability |
|
| Mpi.reorderItemsIndicator |
Reorder Items Indicator. Indicates whether the cardholder is reordering previously purchased merchandise. |
Length: 2 characters Data Type: String Values accepted: • 01 = First time ordered • 02 = Reordered |
|
| Mpi.shippingIndicator | Shipping Indicator
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, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. |
Length: 2 characters Data Type: String Values accepted: • 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.) |
|
| Mpi.MobilePhone.countryCode |
Country code of a mobile phone.
|
Data Type: string Length: 3 characters ITU-E.164 country code | |
| Mpi.MobilePhone.subscriber |
Mobile Phone. Mobile phone (without country code) |
Data Type: string Length: 0 and 15 |
|
| Mpi.threeDSRequestorAuthenticationData |
Merchant Authentication Data. Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail; however the intention is that for each merchant Authentication Method, this field carries data that the ACS can use to verify the authentication process. IE.: 02—field can carry generic merchant authentication information 03—data element can carry information about the provider of the federated ID and related information 04—data element can carry the FIDO attestation data (including the signature) In future versions of the specification, these details are expected to be included |
Length: maximum 2048 bytes Data Type: String Value accepted: Any | |
| Mpi.threeDSRequestorAuthenticationMethod |
Merchant Authentication Method. Mechanism used by the Cardholder to authenticate to the merchant. |
Length: 2 characters Data Type: String Values accepted: • 01 = No merchant authentication occurred (i.e. cardholder “logged in” as guest) • 02 = Login to the cardholder account at the merchant system using merchant’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 • 07–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) • 80–99 = Reserved for DS use |
|
| Mpi.threeDSRequestorAuthenticationTimestamp |
Merchant Authentication Timestamp. Date and time in UTC of the cardholder authentication. |
Length: 14 characters Data Type: DateTime Format accepted: Date format = YYYYMMDDHHMMSS |
|
| Mpi.threeDSRequestorPriorAuthenticationData |
Merchant Prior Transaction Authentication Data. Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail; however the intention is that for each merchant Authentication Method, these fields carry data that the ACS can use to verify the authentication process |
Length: maximum 2048 bytes Format: Any | |
| Mpi.threeDSRequestorPriorAuthenticationMethod |
Merchant Prior Transaction Authentication Method. Mechanism used by the Cardholder to previously authenticate to the merchant. |
Length: 2 characters Data Type: String Values accepted: • 01 = Frictionless authentication occurred by ACS • 02 = Cardholder challenge occurred by ACS • 03 = AVS verified • 04 = Other issuer methods • 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) • 80–99 = Reserved for DS use |
|
| Mpi.threeDSRequestorPriorAuthenticationTimestamp |
Merchant Prior Transaction Authentication Timestamp. Date and time in UTC of the prior cardholder authentication. |
Length: 14 characters Data Type: DateTime Format accepted: Date format = YYYYMMDDHHMMSS |
|
| Mpi.threeDSRequestorPriorReference |
Merchant Prior Transaction Reference. This data element provides additional information to the ACS to determine the best approach for handing a request. |
Length: 36 characters Data Type: String Value accepted: This data element contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder). | |
|
Transaction Type. Identifies the type of transaction being authenticated. |
Length: 2 characters Data Type: String Values accepted: • 01 = Goods/ Service Purchase • 03 = Check Acceptance • 10 = Account Funding • 11 = Quasi-Cash Transaction • 28 = Prepaid Activation and Load |
||
| Mpi.WorkPhone.countryCode |
Work Phone country code. Country code of a work phone |
Data Type: string Length: 3 characters ITU-E.164 country code | |
| Mpi.WorkPhone.subscriber |
Work Phone. Phone used for work purposes (without country code) |
Data Type: string Length: 0 and 15 | |
| TP | To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter. (go to e-Commerce: Dynamic template). |
N/A |
|
| WIN3DS | Way to show the identification page to the customer. Possible values:
|
An Maximum 6 characters |
|
| ADDRMATCH |
addrMatch Indicates whether we consider the billing and shipping address to be identical. 1=yes 0=no |
Length: 1 character Values accepted: • 1=yes • 0=no | |
| TRXDATE |
purchaseDate Transaction date |
MM/DD/YY | |
| ECOM_SHIPTO_POSTAL_CITY |
shipAddrCity Shipping city |
Length: Variable, max 40 | |
| ECOM_SHIPTO_POSTAL_STREET_LINE1 |
shipAddrLine1 Shipping address, first line |
Length: Variable, max 35 | |
| ECOM_SHIPTO_POSTAL_STREET_LINE2 |
shipAddrLine2 Shipping address, second line |
Length: Variable, max 35 | |
| ECOM_SHIPTO_POSTAL_POSTALCODE |
shipAddrPostCode Shipment postal code |
Length: Variable, max 10 | |
| ECOM_SHIPTO_POSTAL_COUNTRYCODE |
shipAddrCountry Shipment country code |
Length max 2
|
5. Monitor progress of 3DSv2 implementation
In order to monitor the progress of your implementation of 3DSv2 within the live environment, you can check individual transactions within the ePDQ back office to see if 3DSv1 or 3DSv2 was used. You can also download a report from ePDQ and, provided you include ‘VERSION_3DS’ within your Electronic Reporting dynamic parameters, the listing will also show.
You can locate this confirmation via the low level transaction detail within the back office. This can be located via the Operations > View Transactions menu – simply search for any transaction, either by date or specific PAYID, and then click on the PAYID button to show the Transaction Detail.
You can then select the Authentication Log (screenshot below), and this will allow you to view whether the transaction fell back to 3DSv1, and identify any missing parameters, or those with erroneous values, in order to remediate accordingly.