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
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
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

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.


Data Type: 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

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
Values accepted:
true
false

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
Data Type: String
Format accepted:

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
Between 0 and 999999

browserScreenWidth

Browser Screen Width.

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

Data Type: Int
Between 0 and 999999

browserTimeZone

Browser Time Zone.

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

Data Type: Int
Between -840 and 720

browserUserAgent

Browser User Agent.

Exact content of the HTTP user-agent header.

Length: Variable, maximum 2048 characters Data Type: String
Note: If the total length of the UserAgent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.

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".
The language value is based on ISO 639-1.
The country value is based on ISO 3166-1.

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
Special characters are allowed, but quotes must be avoided. Most acquirers don’t check the customer name since names can be written in different ways.

Mpi.carteBancaire.Usecase

Mandatory for Carte Bancaire

For all integration modes

Type of payment for which an authentication is requested

Length: 2 characters
Data type: String

Values accepted:

  • 01: Single payment (paiement uinique)
  • 02: Fixed amount and Term Subscription (Abonnement Montant Fixe)
  • 03: installment payment (paiement échelonné)
  • 04: payment at delivery (paimement à la livraison)
  • 05: other subscription (autres abonnements)
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

 

212.23.45.96

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
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

EMAIL

email

Customer’s email address

Length: Variable, max 50

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
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
Data Type: String
Values accepted:

  • 01 = No preference
  • 02 = No challenge requested
  • 03 = Challenge requested: merchant Preference 
  • 04 = Challenge requested: Mandate
  • 05 = No Challenge Requested [transactional risk analysis is already performed]
  • 06 = No Challenge Requested [Data share only]
  • 07 = No Challenge Requested [SCA is already
    Performed]
  • 80-99 = Reserved for DS use
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
Format: integer 1=> 99
Values accepted

  • 1 (represents fraud rate less than or equal to 1 basis point [bp], which is 0.01%)
  • 2 (represents fraud rate between 1 bp + - and 6 bps)
  • 3 (represents fraud rate between 6 bps + - and 13 bps)
  • 4 (represents fraud rate between 13 bps + - and 25 bps)
  • 5 (represents fraud rate greater than 25 bps)
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.

Length: max 1 character
Format accepted: boolean
Value accepted:

  • Y
  • N
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
Data Type: String
Values accepted:

  • 01 = Changed during this transaction
  • 02 = Less than 30 days
  • 03 = 30−60 days
  • 04 = More than 60 days
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
Data Type: String
Values accepted:
• 01 = No account (guest check-out)
• 02 = During this transaction
• 03 = Less than 30 days
• 04 = 30−60 days
• 05 = More than 60 days

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
Data Type: Date
Format accepted:
Date format = YYYYMMDD

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:

  • TRUE
  • FALSE
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:
  • 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.

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

Mpi.carteBancaire.AcquirerExemption

Request for application of RTS Acquirer Transaction Risk Analysis exemption

Data Type: Boolean
Values accepted:
true
false
Mpi.carteBancaire.MerchantScore

Your calculated score for this transaction

Data type: int
Values accepted: Score provided by the merchant to DS ifavailable, i.e:

= any value
e.g. "data" : {"value"
: "Method 023 : A+"}
Mpi.carteBancaire.NumberOfItems

Number of items of the current order

Data type: int
Values accepted: Between 00 and 99 (99 for items >= 99)
Mpi.carteBancaire.Usecase

Type of payment for which an authentication is requested

Length: 2 characters
Data type: String

Values accepted:

  • 01: Single payment (paiement uinique)
  • 02: Fixed amount and Term Subscription (Abonnement Montant Fixe)
  • 03: installment payment (paiement échelonné)
  • 04: payment at delivery (paimement à la livraison)
  • 05: other subscription (autres abonnements)