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 (only applicable to server-to-server integration)
- Recommended parameters
- Optional parameters
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. 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. 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 |
CreatePaymentRequest.CardPaymentMethodSpecificInput.ThreeDSecure. |
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 |
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. |
Data type: Boolean |
CreatePaymentRequest.CardPaymentMethodSpecificInput.Card. CardholderName |
The cardholder's name on the card. |
Data Type: String |
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
|
Data Type: string |
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:
|
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
|
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:
|
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:
|
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:
|
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:
|
order.customer.account.hadSuspiciousActivity | Specifies if you have experienced suspicious activity on the account of the customer | Data Type: Boolean Values accepted:
|
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:
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:
|
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:
|
order.shoppingCart.reOrderIndicator | Indicates whether the cardholder is reordering previously purchased item(s) | Data Type: Boolean Values accepted:
|
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
|
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 |
order.additionInput.typeInformation.transactionType |
Identifies the type of transaction being authenticated. |
Length: x characters Data Type: String Value accepted:
|
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 |
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 |