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 using our Worldline Hosted Payment Page, we will capture these parameters for you. If you are processing transactions via DirectLink, you need to add them manually to your request.

Parameter
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
Data Type: String
Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion

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.


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.

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.

browserScreenHeight

Browser Screen Height.

Total height of the Cardholder’s screen in pixels. Value is returned from the screen height property.

browserScreenWidth

Browser Screen Width.

Total width of the cardholder’s screen in pixels. Value is returned from the screen width property.

browserTimeZone

Browser Time Zone.

Time difference between UTC time and the Cardholder browser local time, in minutes.

browserUserAgent

Browser User Agent.

Exact content of the HTTP user-agent header.

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)

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)

EXCEPTIONURL

URL of the webpage to show the customer when the payment result is uncertain.

(E.g. http://www.myshop.com/exception.html)

LANGUAGE

The payment page languages currently offered to the buyer (card holder / account holder), for example: “en_US”

FLAG3D

Fixed value: ‘Y’

Instructs our system to perform 3-D Secure identification if necessary.

CN

cardholderName

Mpi.carteBancaire.Usecase

Mandatory for Carte Bancaire

For all integration modes

Type of payment for which an authentication is requested

REMOTE_ADDR

Mandatory for Carte Bancaire

For DirectLink requests

browserIP

IP address of the customer (only for Fraud Detection Module). For interfaces where our system handles the dialog with the customer (e.g. e-Commerce) the REMOTE_ADDR is directly captured by us. For other interfaces, the merchant needs to send the customer's IP address with the transaction details

 

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

Parameter
ECOM_BILLTO_POSTAL_CITY

billAddrCity

Invoicing city

ECOM_BILLTO_POSTAL_COUNTRYCODE

billAddrCountry

Invoicing country code

ECOM_BILLTO_POSTAL_STREET_LINE1

billAddrLine1

Billing address, first line

ECOM_BILLTO_POSTAL_STREET_LINE2

billAddrLine2

Billing address, second line

ECOM_BILLTO_POSTAL_POSTALCODE

billAddrPostCode

Invoicing Postal Code

EMAIL

email

Customer’s email address

For Hosted Payment Page implementations, please also refer to the 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
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.

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.

Mpi.secureCorporatePayment

Secure Corporate Payment

Indicates that dedicated payment processes and procedures were used and that potential secure corporate payment exemption applies.
Send this field only with Y if the acquirer exemption field is blank, as
acquirer exemption and secure payment are mutually exclusive.
However, the directory server (DS) will not validate the conditions in the extension. The DS will pass data as sent.
You can optionally indicate if they apply to the dedicated processes and protocols as per PSD2 RTS Article 17, which would potentially allow the issuer to claim the secure corporate payment exemption.

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.

Mpi.cardholderAccountDate

Cardholder Account Date.

Date that the cardholder opened the account with the merchant.

Mpi.cardholderAccountPasswordChange

Cardholder Account Password Change.

Date that cardholder’s account with the merchant had a password change or account reset.

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.

Mpi.numberOfPurchaseWithAccountInTheLastSixMonths

Cardholder Account Purchase Count.

Number of purchases with this cardholder account during the previous six months.

Mpi.paymentAccountAge

Payment Account Age.

Date that the payment account was enrolled in the cardholder’s account with the merchant.

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.

Mpi.provisionAttemptsInTheLast24Hours

Number of Provisioning Attempts Day.

Number of Add Card attempts in the last 24 hours.

Mpi.shippingAddressUsage

Shipping Address Usage.

Date when the shipping address used for this transaction was first used with the merchant.

Mpi.shippingAddressWasFirstUsed

Shipping Address Usage Indicator.

Indicates when the shipping address used for this transaction was first used with the merchant.

Mpi.shippingNameAndCardholderNameAreIdentical

Shipping Name Indicator.

Indicates if the Cardholder

Name on the account is

identical to the shipping

Name used for this

transaction.

Mpi.suspiciousAccountActivityDetected

Suspicious Account Activity.

Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account.

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.

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.

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.

Mpi.HomePhone.countryCode

Home Phone Country Code.

Country code of a home phone.

Mpi.HomePhone.subscriber

Home Phone.

Home phone (without country code)

Mpi.deliveryEmailAddress

Delivery Email Address.

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

Mpi.deliveryTimeframe

Delivery Timeframe.

Indicates the merchandise

delivery timeframe.

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)

Mpi.giftCardCount

Gift Card Count.

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

Mpi.giftCardCurrency

Gift Card Currency.

For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

Mpi.preOrderDate

Pre-Order Date.

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

Mpi.cardholderAccountAgeIndicator

Cardholder Account Age Indicator:

Length of time that the

cardholder has had the account

with the merchant.

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.

Mpi.preOrderPurchaseIndicator Pre-Order Purchase Indicator.
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
Mpi.reorderItemsIndicator

Reorder Items Indicator.

Indicates whether the cardholder is reordering previously purchased merchandise.

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.

Mpi.MobilePhone.countryCode

Country code of a mobile phone.

Mpi.MobilePhone.subscriber

Mobile Phone.

Mobile phone (without country code)

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

Mpi.threeDSRequestorAuthenticationMethod

Merchant Authentication Method.

Mechanism used by the Cardholder to authenticate to the merchant.

Mpi.threeDSRequestorAuthenticationTimestamp

Merchant Authentication Timestamp.

Date and time in UTC of the cardholder authentication.

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

Mpi.threeDSRequestorPriorAuthenticationMethod

Merchant Prior Transaction Authentication Method.

Mechanism used by the Cardholder to previously authenticate to the merchant.

Mpi.threeDSRequestorPriorAuthenticationTimestamp

Merchant Prior Transaction Authentication Timestamp.

Date and time in UTC of the prior cardholder authentication.

Mpi.threeDSRequestorPriorReference

Merchant Prior Transaction Reference.

This data element provides additional information to the ACS to determine the best approach for handing a request.

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

Mpi.WorkPhone.subscriber

Work Phone.

Phone used for work purposes (without country code)

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).
WIN3DS Way to show the identification page to the customer. Possible values:
  • MAINW: display the identification page in the main window (default value).
  • POPUP: display the identification page in a pop-up window and return to the main window at the end.
  • POPIX: display the identification page in a pop-up window and remain in the pop-up window.
ADDRMATCH

addrMatch

Indicates whether we consider the billing and shipping address to be identical. 1=yes 0=no

TRXDATE

purchaseDate

Transaction date

ECOM_SHIPTO_POSTAL_CITY

shipAddrCity

Shipping city

ECOM_SHIPTO_POSTAL_STREET_LINE1

shipAddrLine1

Shipping address, first line

ECOM_SHIPTO_POSTAL_STREET_LINE2

shipAddrLine2

Shipping address, second line

ECOM_SHIPTO_POSTAL_POSTALCODE

shipAddrPostCode

Shipment postal code

ECOM_SHIPTO_POSTAL_COUNTRYCODE

shipAddrCountry

Shipment country code

Mpi.carteBancaire.AcquirerExemption

Request for application of RTS Acquirer Transaction Risk Analysis exemption

Mpi.carteBancaire.MerchantScore

Your calculated score for this transaction

Mpi.carteBancaire.NumberOfItems

Number of items of the current order

Mpi.carteBancaire.Usecase

Type of payment for which an authentication is requested