Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above
  1. Home
  2. Payment Performance
  3. 3-D Secure
  4. 3-D Secure V2 parameters

3-D Secure V2 parameters

Introduction

This list contains all relevant 3-D Secure V2 parameters. It is split up in three sections:

Mandatory parameters

If you are using our Hosted Checkout solution, we will capture these parameters for you. If you are processing transactions via Create Payment, you need to add them manually to your request.

Parameter Description Format
CreatePaymentRequest.Order.Customer.
Device.AcceptHeader		 Browser Accept Headers.
Exact content of the HTTP accepts 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
CreatePaymentRequest.Order.Customer.
Device.BrowserData.ColorDepth		 Browser Color Depth.
ColorDepth in bits. Value is returned from the screen.colorDepth property.
If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.
Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".		 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
CreatePaymentRequest.Order.Customer.
Device.BrowserData.JavaEnabled		 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
CreatePaymentRequest.Order.Customer.
Device.Locale		 Browser Language.
Locale of the client device/browser. Returned in the browser from the navigator.language property.
If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.		 Length: Variable, 1–8 characters
Data Type: String
Format accepted:
xx, xxx, xx-XX or xx-xxxx-xx.
CreatePaymentRequest.Order.Customer.
Device.Locale		 Browser Language.
Locale of the client device/browser. Returned in the browser from the navigator.language property.
If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.		 Length: Variable, 1–8 characters
Data Type: String
Format accepted:
xx, xxx, xx-XX or xx-xxxx-xx.
CreatePaymentRequest.Order.Customer.
Device.BrowserData.ScreenHeight		 Height of the screen in pixels. Value is returned from the screen.height property.
If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.
Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".		 Data Type: Int
Between 0 and 999999
CreatePaymentRequest.Order.Customer.
Device.BrowserData.ScreenWidth		 Width of the screen in pixels. Value is returned from the screen.width property.
If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.
Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".		 Data Type: Int
Between 0 and 999999
CreatePaymentRequest.Order.Customer.
Device.TimezoneOffsetUtcMinutes

Browser Time Zone.
Offset in minutes of timezone of the client versus the UTC. Value is returned by the JavaScript getTimezoneOffset() Method.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

 Data Type: Int
Between -840 and 720
CreatePaymentRequest.Order.Customer.
Device.UserAgent

Browser User Agent.
User-Agent of the client device/browser from the HTTP Headers.

As a fall-back we will use the userAgent that might be included in the encryptedCustomerInput, but this is captured client side using JavaScript and might be different.

Length: Variable, maximum 2048 characters
Data Type: String

CreatePaymentRequest.CardPaymentMethodSpecificInput.ThreeDSecure.
RedirectionData.ReturnUrl

The URL that the customer is redirected to after the payment flow has finished. You can add any number of key value pairs in the query string that, for instance help you to identify the customer when they return to your site. Please note that we will also append some additional key value pairs that will also help you with this identification process. Note: The provided URL should be absolute and contain the protocol to use, e.g. http:// or https://. For use on mobile devices a custom protocol can be used in the form of protocol://. This protocol must be registered on the device first. URLs without a protocol will be rejected (E.g. http://www.myshop.com/accept.html).

Data Type: String
Alphanumeric
Length: Variable, maximum 200 characters
SkipAuthentication

true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
false = 3D Secure authentication will not be skipped for this transaction.
Note: This is only possible if your account in our system is setup for 3D Secure authentication and if your configuration in our system allows you to override it per transaction.

Data type: Boolean
Accepted values: true, false
CreatePaymentRequest.CardPaymentMethodSpecificInput.Card.
CardholderName

The cardholder's name on the card.

Data Type: String
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.
CardPaymentMethodSpecificInput.PaymentProduct130SpecificInput.
ThreeDSecure.usecase

Mandatory for Carte Bancaire

Indicates the type of payment for which an authentication is requested.

If left out, our platform populates the property with default value single-amount

See our API reference for possible values

Data Type: String
order.customer.device.ipAddress

Mandatory for Carte Bancaire

browserIP
The IP address of the customer client from the HTTP Headers (only for Fraud Detection Module). For interfaces where our system handles the dialog with the customer (e.g. Hosted Checkout) the ipAddress is directly captured by us. For other interfaces, the merchant needs to send the customer's IP address with the transaction details.

 

Data Type: string
Length: variable max 45
Example: 212.23.45.96

Recommended parameters

The major card schemes highly recommend including these, as they will enhance the chance of a frictionless flow.

Parameter Description Format
order.customer.billingaddress.city Invoicing city Data Type: string
Length: Variable, max 25
order.customer.billingAddress.countryCode Invoicing country code Data Type: string
Length max 2
order.customer.billingAddress.street Street name Data Type: string
Length: Variable, max 35
order.customer.billingAddress.houseNumber House number Data Type: string
Length: Variable, max 35
order.customer.billingAddress.additionalInfo Second line of street or additional address information Data Type: string
Length: Variable, max 35
order.customer.billingAddress.zip Zip code Data Type: string
Length: Variable, max 10
order.customer.contactDetails.emailAddress email
Customer’s email address		 Data Type: string
Length: Variable, max 50

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 Description Format
cardPaymentMethodSpecificInput.threeDSecure.challengeIndicator Allows you to indicate if you want the customer to be challenged for extra security on this transaction. Length: Variable
Data Type: String
Possible values:
  • no-preference - You have no preference whether or not to challenge the customer (default)
  • no-challenge-requested - you prefer the cardholder not to be challenged
  • challenge-requested - you prefer the customer to be challenged
  • challenge-required - you require the customer to be challenged
  • no-challenge-requested-risk-analysis-performed – letting the issuer know that you have already assessed the transaction with fraud prevention tool
  • no-challenge-requested-data-share-only – sharing data only with the DS
  • no-challenge-requested-consumer-authentication-performed – authentication already happened at your side – when login in to your website
  • no-challenge-requested-use-whitelist-exemption – cardholder has whitelisted you at with the issuer
  • challenge-requested-whitelist-prompt-requested – cardholder is trying to whitelist you
  • request-scoring-without-connecting-to-acs – sending information to CB DS for a fraud scoring
cardPaymentMethodSpecificInput.threeDSecure.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: bolean
Value accepted:

  • true
  • false
order.customer.account.changedDuringCheckout true = the customer made changes to their account during this checkout
false = the customer didn't change anything to their account during this checkout/n
The changes ment here are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.		 Data Type: boolean
Values accepted:
  • true = the customer made changes to their account during this checkout
  • false = the customer didn't change anything to their account during this checkout
order.customer.account.changeDate The last date (YYYYMMDD) on which the customer made changes to their account with you. These are changes to billing & shipping address details, new payment account (tokens), or new users(s) added. Data type: string
Max length: 8 characters
order.customer.account.createDate The date (YYYYMMDD) on which the customer created their account with the merchant. Length: 8 characters
Data Type: Date
Format accepted:
Date format = YYYYMMDD
order.customer.account.passwordChangeDate The last date (YYYYMMDD) on which the customer changed their password for the account used in this transaction Length: 8 characters
Data Type: Date
Format accepted:
Date format = YYYYMMDD
order.customer.account.passwordChangedDuringCheckout

Indicates if the password of an account is changed during this checkout

 Data Type: boolean
Values accepted:
  • true = the customer made changes to their password of the account used during this checkout
  • false = the customer didn't change anything to their password of the account used during this checkout
order.customer.account.paymentActivity.numberOfPurchasesLast6Months Number of successful purchases made by this customer with you in the last 6 months Data Type: Int
Between 0 and 9999
order.customer.account.paymentAccountOnFile.createDate The date (YYYYMMDD) when the payment account on file was first created.
In case a token is used for the transaction we will use the creation date of the token in our system in case you leave this property empty.		 Length: 8 characters
Data Type: Date
Format accepted:
Date format = YYYYMMDD
order.customer.accountType

Type of the customer account that is used to place this order.

 Length: 2 characters
Data Type: String
Values accepted:
  • none - The account that was used to place the order with is a guest account or no account was used at all
  • created - The customer account was created during this transaction
  • existing - The customer account was an already existing account prior to this transaction
order.customer.account.paymentAccountOnFile.numberOfCardOnFileCreationAttemptsLast24Hours Number of attempts made to add new card to the customer account in the last 24 hours Data Type: Int Between 0 and 999
order.shipping.firstUsageDate Date when the shipping details for this transaction were first used. Length: 8 characters
Data Type: Date
Format accepted:
Date format = YYYYMMDD
order.shipping.isFirstUsage Indicator if this shipping address is used for the first time to ship an order Data Type: boolean
Values accepted:
  • true = the shipping details are used for the first time with this transaction
  • false = the shipping details have been used for other transactions in the past
order.customer.account.hadSuspiciousActivity Specifies if you have experienced suspicious activity on the account of the customer Data Type: Boolean
Values accepted:
  • true = you have experienced suspicious activity (including previous fraud) on the customer account used for this transaction
  • false = you have experienced no suspicious activity (including previous fraud) on the customer account used for this transaction
order.customer.account.paymentActivity.numberOfPaymentAttemptsLast24Hour Number of payment attempts (so including unsuccessful ones) made by this customer with you in the last 24 hours Data Type: Int
Between 0 and 999
order.customer.account.paymentActivity.numberOfPaymentAttemptsLastYear Number of payment attempts (so including unsuccessful ones) made by this customer with you in the last 12 months Data Type: Int
Between 0 and 999
cardPaymentMethodSpecificInput.threeDSecure.challengeCanvasSize Dimensions of the challenge window that potentially will be displayed to the customer. The challenge content 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 customer browser window. Length: 2 characters
Data Type: String
Value accepted:
  • 250 x 400 (default)
  • 390 x 400
  • 500 x 600
  • 600 x 400
  • full screen

If you don't send this parameter, then the default value will be 250x400
order.customer.contactDetails.phoneNumber Phone number of the customer Data Type: string
Length: 1-18 characters
order.shipping.emailAddress Email address linked to the shipping Length: maximum 254 characters
Data Type: String
order.shipping.type Indicates the merchandise delivery timeframe. Length: 2 characters
Data Type: String
Values accepted:
  • electronic = For electronic delivery (services or digital goods
  • same-day = For same day deliveries
  • overnight = For overnight deliveries
  • 2-day-or-more = For two day or more delivery time
order.shoppingCart.giftCardPurchase.amountOfMoney.amount For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s). Amount in cents and always having 2 decimals Length: maximum 15 characters Data Type: Int Between 0 and 999999999999999
order.shoppingCart.giftCardPurchase.numberOfGiftCards Number of gift cards that are purchased through this transaction Data Type: Int Between 0 and 99
order.shoppingCart.giftCardPurchase.amountOfMoney.currencyCode For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. Length: 3 characters
Data Type: String
order.shoppingCart.preOrderItemAvailabilityDate Date when the preordered item becomes available Length: 8 characters
Data Type: Date Format accepted: Date format = YYYYMMDD
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
order.shoppingCart.isPreOrder The customer is pre-ordering one or more items Data Type: Boolean
Values accepted:
  • true
  • false
order.shoppingCart.reOrderIndicator Indicates whether the cardholder is reordering previously purchased item(s) Data Type: Boolean
Values accepted:
  • true = the customer is re-ordering at least one of the items again
  • false = this is the first time the customer is ordering these items
order.shipping.addressIndicator

Indicates shipping method chosen for the transaction.

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.

 Data Type: String
Values accepted:
• same-as-billing = the shipping address is the same as the billing address
• another-verified-address-on-file-with-merchant = the address used for shipping is another verified address of the customer that is on file with you
• different-than-billing = shipping address is different from the billing address
• ship-to-store = goods are shipped to a store (shipping address = store address)
• digital-goods = electronic delivery of digital goods
• travel-and-event-tickets-not-shipped = travel and/or event tickets that are not shipped
• other = other means of deliverycardholder’s specific transaction, not their general business
order.customer.contactDetails.mobilePhoneNumber International version of the mobile phone number of the customer including the leading + (i.e. +16127779311) Data Type: string Length: 18 characters
order.customer.account.authentication.method Authentication used by the customer on your website Length: 2 characters
Data Type: String
Values accepted:
• guest = no login occurred, customer is logged in as guest
• merchant-credentials = the customer logged in using credentials that are specific to you
• federated-id = the customer logged in using a federated ID
• issuer-credentials = the customer logged in using credentials from the card issuer (of the card used in this transaction)
• third-party-authentication = the customer logged in using third-party authentication
• fido-authentication = the customer logged in using a FIDO authenticator
order.customer.account.authentication.utcTimestamp Timestamp of the authentication of the customer to their account with you Length: 12 characters
Data Type: DateTime Format accepted: Date format = YYYYMMDHHMM
cardPaymentMethodSpecificInput.threeDsecure.priorThreeDSecureData.method

Method of authentication used for this transaction

Data type : string
Length: 30 characters
Values accepted:

  • frictionless = The authentication went without a challenge
  • challenged = Cardholder was challenged
  • avs-verified = The authentication was verified by AVS
  • other = Another issuer method was used to authenticate this transaction
cardPaymentMethodSpecificInput.priorThreeDSecureData.utcTimestamp

Timestamp in UTC of the 3-D Secure authentication of prior transaction.

 Length: 14 characters
Data Type: DateTime Format accepted: Date format = YYYYMMDDHHMMSS
cardPaymentMethodSpecificInput.priorThreeDSecureData.acsTransactionId

The ACS Transaction ID for a prior 3-D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the customer)

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).
order.additionInput.typeInformation.transactionType

Identifies the type of transaction being authenticated.

 Length: x characters Data Type: String
Value accepted:
  • purchase = The purpose of the transaction is to purchase goods or services (Default)
  • check-acceptance = The purpose of the transaction is to accept a 'check'/'cheque'
  • account-funding = The purpose of the transaction is to fund an account
  • quasi-cash = The purpose of the transaction is to buy a quasi cash type product that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets or casino gaming chips
  • prepaid-activation-or-load = The purpose of the transaction is to activate or load a prepaid card
order.customer.contactDetails.workPhoneNumber

International version of the work phone number of the customer including the leading + (i.e. +31235671500)

 Data Type: string
Length: x characters
cardPaymentMethodSpecificInput.order.shipping.address.city

Shipping city

 Data type: string
Length: Variable, max 40
cardPaymentMethodSpecificInput.order.shipping.address.street

Shipping address, Street name

 Data type: string
Length: Variable, max 35
cardPaymentMethodSpecificInput.order.shipping.address.houseNumber

Shipping address, house number

 Data type: string
Length: Variable, max 35
cardPaymentMethodSpecificInput.order.shipping.address.additionalInfo

Shipping address, Second line of street or additional address information

 Data type: string
Length: Variable, max 35
cardPaymentMethodSpecificInput.order.shipping.address.zip

Shipment zip code

 Data type: string
Length: Variable, max 10
cardPaymentMethodSpecificInput.order.shipping.address.countryCode

Shipment country code
ISO 3166-1 alpha-2 country code

 Data type: string
Length max 2
order.additionalInput.airlineData.flightIndicator
   

Indicator representing the type of flight on the itinerary

 Data type: string

order.additionalInput.airlineData.ticketCurrency

Three-letter ISO 4217 currency code representing the currency in which ticket purchase amount is expressed

 Data type: string
Length max 3
order.additionalInput.airlineData.passengers.airlineLoyaltyStatus

Airline loyalty program level for the passenger on the itinerary

 Data type: string
order.additionalInput.airlineData.passengers.passengerType

Type of passenger on the itinerary

 Data type: string