Request Fields
Initial Request (Hosted and Direct Integration)
These fields should be sent in addition to the Basic Request Fields.
| Field name | Mandatory? | Description |
|---|---|---|
| merchantName | No[1] | Merchant name to use on 3DS challenge form. |
| merchantWebsite | No[1] | Merchant website to use on 3DS challenge form. The website must be a fully qualified URL and include at least the scheme and host components. |
| merchantCategoryCode | No[1] | Merchant category code. |
| threeDSRequired | No[1] | Is 3DS required for this transaction? Possible values are: N – 3DS is not required. Y – Abort if 3DS is not enabled. |
| threeDSCheckPref | No[1] | List of Value is a comma separated list containing one or more of the following values: ‘not known', 'not checked', ' not authenticated', 'attempted authentication', 'authenticated’. |
| threeDSRedirectURL | Yes[2] | A URL on the Merchant’s server to which the ACS can POST the challenge results, thus redirecting the challenge IFRAME to this page. |
| threeDSOptions | No[3] | Record containing 3DS options that can be used by the ACS for advance fraud checking. Refer to the 3-D Secure Options (Hosted and Direct Integration) section for further details. |
| threeDSPolicy | No[1] | 3DS Policy used. Refer to the SCA Using 3-D Secure section for further details. |
| threeDSVersion | No[1] | Force a particular version to be used rather than using the highest available for the transaction details. Use of this request field is not encouraged under normal circumstances. |
| scaExemption | No[1] | An SCA exemption can be used to request that a frictionless flow is preferable. Refer to the Exemptions to Strong Customer Authentication section for further details. |
External Authentication Request (Direct Integration)
These fields should be sent in addition to the Basic Request Fields.
| Field Name | Mandatory | Description |
|---|---|---|
| threeDSVersion | Yes | Specify which 3DS Version was used. Possible values are: 1.0.2 (deprecated), 2.1.0 or 2.2.0. |
| threeDSAuthenticated | If 3DS enrolled | The 3DS authentication status for the credit card. Refer to the 3DS Authentication Status section for details. Possible values are: Y – Authenticated. A – Attempted to authenticate. N – Not authenticated. I – Information only. U – Unable to authenticate. E – Error checking authentication. |
| threeDSXID | If 3DS authenticated | The unique identifier for the transaction in the 3DS system. Refer to the 3DS Authentication Status section for details. |
| threeDSECI | If 3DS authenticated | The Electronic Commerce Indicator (ECI). Refer to the 3DS Authentication Status section for details. |
| threeDSCAVV | If 3DS authenticated | The Cardholder Authentication Verification Value (CAVV). Refer to the 3DS Authentication Status section for details. |
If 3-D Secure is not enabled for the Merchant Account, then any 3-D Secure authentication fields sent in the request are ignored and the transaction is processed as normal without 3-D Secure.
When an external 3-D Secure provider is used then you are responsible for deciding whether to continue at the different 3-D Secure stages and any preferences provided in the MMS or using the threeDSCheckPref request field are ignored.
If the external provider returns an authentication status of ‘R’ then you must not continue with the transaction either with or without 3-D Secure. Do not attempt to send a threeDSAuthentication status of ‘R’ expecting the Gateway to reject the transaction.
Continuation Request (Direct Integration)
These fields may be sent alone.
| Field Name | Mandatory? | Description |
|---|---|---|
| threeDSRef | Yes | The value of the threeDSRef field in the initial Gateway response. |
| threeDSResponse | Yes | The data POSTed back from the ACS when the challenge has completed. |
It is only necessary to send the threeDSRef and the threeDSResponse in the continuation request, because the threeDSRef will identify the Merchant Account and initial request. You can send any of the normal request fields to modify or supplement the initial request. The message need not be signed but it is highly recommended that you do if not sending over a secure server to server connection. Any card details and transaction amount sent in the second request must match those used in the first request, else the second request will fail with a responseCode of 64442 (REQUEST MISMATCH).
3-D Secure Options (Hosted and Direct Integration)
The following options may be sent in the threeDSOptions field to provide additional information to help customise the 3-D Secure experience or to help the ACS decide if a challenge is required.
Some additional information will be automatically provided by the Gateway from standard integration fields unless overridden by providing the associated option. The standard integration field associated with each option is shown in brackets below the options field name. The standard integration field should be used rather than the option, apart from the very rare circumstances where the two must have different values.
A few additional information values, such as the Cardholder’s browser details[[5]], are mandatory and therefore either the standard integration field or the option must be provided. These fields are marked as ‘Yes’ in the Mandatory column of the table below.
Further details what information is mandatory can be found at the end of this section.
The options must be formatted using the record or serialised record formats.
[1] The Hosted Integrations Payment Page will ignore any browser options and use its own details.
| Sub-Field Name | Mandatory? | Description |
|---|---|---|
| accountAgeIndicator | No | Length of time that the cardholder has had the account with the 3DS Requestor. Possible values are: 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 |
| accountChangeDate | No | Date that the cardholder's account with the 3DS Requestor was last changed. Accepted date format is YYYYMMDD. |
| accountChangeIndicator | No | Length of time since the cardholder's account information with the 3DS Requestor was last changed. Possible values are: 01 – Changed during this transaction 02 – Less than 30 days 03 – 30-60 days 04 – More than 60 days |
| accountDate | No | Date that the cardholder opened the account with the 3DS Requestor. Accepted date format is YYYYMMDD. |
| accountDayTransactions | No | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. |
| accountId | No | Identifier for any Cardholder’s account with the Merchant. |
| accountPasswordChangeDate | No | Date that cardholder's account with the 3DS Requestor had a password change or account reset. Accepted date format is YYYYMMDD. |
| accountPasswordChangeIndicator | No | Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset. Possible values are: 01 – No change 02 – Changed during this transaction 03 – Less than 30 days 04 – 30-60 days 05 – More than 60 days |
| accountProvisioningAttempts | No | Number of account provisioning attempts in the last 24 hours. |
| accountPurchaseCount | No | Number of purchases with this cardholder account during the previous six months. |
| accountType | No | Indicates the type of account. Possible values are: 01 – Not applicable 02 – Credit 03 – Debit |
| accountYearTransactions | No | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. |
| acquirerBIN | No | Acquirer bank identification number. (Default on file) |
| acquirerCountryCode | No | Acquirer country code when the Acquirer country differs from the Merchant country and the Acquirer is in the EEA (this could mean that the transaction is covered by PSD2). (Default on file) |
| acquirerMerchantID | No | Acquirer-assigned merchant identifier. (Default on file) |
| acsChallengeMandatedIndicator | No | Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables. |
| addressMatch | No | Indicates to the ACS whether the cardholder shipping address and billing address are the same. Possible values are: Y – Shipping address matches billing address. N – Shipping address does not match billing address. |
| authenticationIndicator | No | Provides additional information to the ACS to determine the best approach for handing an authentication request. Possible values are: 01 – Payment - default 02 – Recurring 03 – Instalment 04 – Add Card 05 – Maintain Card 06 – Verify Cardholder 07 – Billing Agreement |
billingAddressCity (customerTown) | No | The city of the address. Maximum length is 50 characters. |
billingAddressCountryCode (customerCountryCode) | No | The country of the address as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents. |
billingAddressLine1 (customerAddress) | No | The first line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
| billingAddressLine2 | No | The second line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
| billingAddressLine3 | No | The third line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
billingAddressPostcode (customerPostcode) | No | The ZIP or other postal code of the address. Maximum length is 16 characters. |
| billingAddressState | No | The state or province of the address as an ISO 3166-2 country subdivision code. Maximum length is 3 characters. |
browserAcceptHeader (deviceAcceptContent) | Yes[1] | HTTP accept header sent from the Cardholder’s browser. |
browserIPAddress (deviceIpAddress) | Yes[1] | IP address of the Cardholder’s browser. This can be an IP v4 address using dotted decimal notation (eg 1.12.123.255) or an IP v6 address using colon hexadecimal notation (eg 2011:0db8:85a3:0101: 0101:8a2e:0370:7334) |
browserJavaEnabled (deviceCapabilities) | Yes[1] | Ability of the Cardholder’s browser to execute Java. Possible values are[2]: true – browser can execute Java false – browser cannot execute Java |
browserJavaScriptEnabled (deviceCapabilities) | Yes[1] | Ability of the Cardholder’s browser to execute JavaScript. Possible values are [2]: true – browser can execute JavaScript false – browser cannot execute JavaScript |
browserLanguage (deviceAcceptLanguage) | Yes[1] | The Cardholder’s browser language. The browser language as defined in IETF BCP 47. |
browserScreenColourDepth or browserScreenColorDepth (deviceScreenResolution) | Yes[1],[3] | The screen colour depth of the Cardholder’s browser. A value representing the bit depth of the colour palette, in bits per pixel, for displaying images. Possible values are: 1, 4, 8, 15, 16, 24, 32, 48. |
browserScreenHeight (deviceScreenResolution) | Yes[1],[3] | The screen height of the Cardholder’s browser. |
browserScreenWidth (deviceScreenResolution) | Yes[1],[3] | The screen width of the Cardholder’s browser. |
browserTimeZone (deviceTimeZone) | Yes[1] | The difference between UTC time and the cardholder's browser local time in minutes. |
browserUserAgent (deviceIdentity) | Yes[1] | The User-Agent header provided by the Cardholder’s browser. |
cardholderEmail (customerEmail) | No | The Cardholder’s email address. From 12 August 2024, for Visa transactions, this field is mandatory unless the Cardholder Phone Number is provided. |
cardholderHomePhone (customerPhone) | No | The Cardholder’s home phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”). From 12 August 2024, for Visa transactions, this field is mandatory unless the Cardholder Email is provided. |
cardholderMobilePhone (customerMobile) | No | The Cardholder’s mobile phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”). |
cardholderName (customerName) | No | Name of the Cardholder. Limited to the alphanumeric characters listed in EMV Book 4, Annex B. From 12 August 2024, for Visa transactions, this field is mandatory. |
| cardholderWorkPhone | No | The Cardholder’s work phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”). |
| challengeWindowSize | No | The 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. Possible values are: 01 – 250 x 400 02 – 390 x 400 (default) 03 – 500 x 600 04 – 600 x 400 05 – Full screen |
deliveryEmailAddress (deliveryEmail) | No | Email Address to which the merchandise was delivered for electronic delivery. |
| deliveryTimeframe | No | Merchandise Delivery Timeframe. Possible values are: 01 – Electronic Delivery 02 – Same day shipping 03 – Overnight shipping 04 – Two-day or more shipping |
| giftCardAmount | No | 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). |
| giftCardCount | No | For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. |
| giftCardCurrencyCode | No | For prepaid or gift card purchase, the currency code of the card as an ISO 4217 3-digit code or its 3 letter equivalent. |
| instalmentPaymentData or installmentPaymentData | No | Indicates maximum number of authorizations permitted for instalment payments. Value must be greater than 1. |
merchantCategoryCode (merchantCategoryCode) | No | Code describing the Merchant's type of business, product, or service. |
merchantCountryCode (countryCode) | No | Country code of the merchant as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents. |
| merchantFraudRate | No | Merchant’s fraud rate in the EEA (all EEA card fraud divided by all EEA card volumes) calculated as per PSD2 RTS. This value is sent to Mastercard only who will not calculate or validate the fraud score. Value will be a numeric value, between 1 and 99, representing the fraud rate, such as: 1 – less than or equal to 1 basis point (bp), which is 0.01% 2 – between 1 bp + - and 6 bps 3 – between 6 bps + - and 13 bps 4 – between 13 bps + - and 25 bps 5 – greater than 25 bps |
merchantName (merchantName) | No | Merchant name. |
| paymentAccountAge | No | Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. Accepted date format is YYYYMMDD. |
| paymentAccountAgeIndicator | No | Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor. Possible values are: 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 |
| preOrderDate | No | For a pre-ordered purchase, the expected date that the merchandise will be available. Accepted date format is YYYYMMDD. |
| preOrderPurchaseIndicator | No | Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. Possible values are: 01 – Merchandise available 02 – Future availability |
| priorAuthData | No | Data that documents and supports a specific authentication process. |
| priorAuthMethod | No | Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. Part of the optional 3DS Requestor Prior Transaction Authentication Information that contains information about a 3DS cardholder authentication that occurred prior to the current transaction. Possible values are: 01 – Frictionless authentication occurred by ACS 02 – Cardholder challenge occurred by ACS 03 – ACS verified 04 – Other issuer methods |
| priorAuthTimestamp | No | Date and time in UTC of the prior cardholder authentication. Accepted date format is YYYYMMDDHHMM. |
| priorReference | No | Provides additional information to the ACS to determine the best approach for handling a request. It contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder). |
| recurringExpDate | No | This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD |
| recurringFrequency | No | This field indicates the minimum number of days between authorizations. |
| reorderItemsIndicator | No | Indicates whether the cardholder is reordering previously purchased merchandise. Possible values are: 01 – First time ordered 02 – Reordered |
| reqAuthData | No | 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 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. |
| reqAuthMethod | No | Method used by the Cardholder to authenticate to the 3DS Requestor. Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account. Possible values are: 01 – No 3DS Requestor authentication occurred (ie cardholder "logged in" as guest) 02 – Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials 03 – Login to the cardholder account at the 3DS Requestor system using federated ID 04 – Login to the cardholder account at the 3DS Requestor system using issuer credentials 05 – Login to the cardholder account at the 3DS Requestor system using third-party authentication 06 – Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator |
| reqAuthTimestamp | No | Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM. |
| requestorChallengeIndicator | No | Indicates whether a challenge is requested for this transaction. For example: you may be using this to obtain SCA and not want to be challenged as you have provided an exemption. This also allows you to request a challenge when adding a card to a wallet or to follow mandates. Possible values are: 01 – No preference 02 – No challenge requested 03 – Challenge requested: 3DS Requestor Preference 04 – Challenge requested: Mandate 05 – No challenge requested (TRA is already performed) 06 – No challenge requested (data share only) 07 – No challenge requested (SCA is already performed) 08 – No challenge requested (utilize whitelist exemption) 09 – Challenge requested (whitelist prompt requested) Values 05 to 09 are for protocol version 2.2.0 but will be accepted for 2.1.0 and 05 to 08 will be downgraded to 02, and 09 to 01. Values 05 to 07 will be passed to Mastercard as part of their 'Merchant Data' extension. Values 08 and 09 are only valid for protocol version 2.2.0. |
| requestorID | No | Directory server assigned 3DS Requestor identifier. (Default on file) |
| requestorName | No | Directory server assigned 3DS Requestor name. (Default on file) |
requestorURL (merchantWebsite) | No | 3DS Requestor website or customer care site. |
| secureCorporatePaymentIndicator | No | Indicates dedicated payment processes and procedures were used, potential secure corporate payment exemption applies. |
| serverOperatorID | No | 3DS Server identifier. (Default on file) |
| serverRefNumber | No | Assigned server reference number. (Default on file) |
| shipAddressUsageDate | No | Date when the shipping address used for this transaction was first used with the 3DS Requestor. Accepted date format is YYYYMMDD. |
| shipAddressUsageIndicator | No | Indicates the length of time since the shipping address used for this transaction was first used with the 3DS Requestor. Possible values are: 01 – This transaction 02 – Less than 30 days 03 – 30-60 days 04 – More than 60 days |
| shipIndicator | No | 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, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item. Possible values are: 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) |
| shipNameIndicator | No | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Possible values are: 01 – Account Name identical to shipping Name 02 – Account Name different than shipping Name |
shippingAddressCity (deliveryTown) | No | The city of the address. The maximum length is 50 characters. |
shippingAddressCountryCode (deliveryCountryCode) | No | The country of the address as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents. |
shippingAddressLine1 (deliveryAddress) | No | The first line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
| shippingAddressLine2 | No | The second line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
| shippingAddressLine3 | No | The third line of the street address or equivalent local portion of the address. Maximum length is 50 characters. |
shippingAddressPostcode (deliveryPostcode) | No | The ZIP or other postal code of the address. Maximum length is 16 characters. |
| shippingAddressState | No | The state or province of the address as an ISO 3166-2 country subdivision code. Maximum length is 3 characters. |
| suspiciousAccountActivity | No | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. Possible values are: 01 – No suspicious activity has been observed 02 – Suspicious activity has been observed |
| transactionType | No | Identifies the type of transaction being authenticated. This field is required in some markets (eg for Merchants in Brazil). Possible values are: 01 – Goods/ Service Purchase 03 – Check Acceptance 10 – Account Funding 11 – Quasi-Cash Transaction 28 – Prepaid Activation and Load |
| whitelistStatus | No | Whitelist status. Possible values are: Y – 3DS Requestor is whitelisted by cardholder N – 3DS Requestor is not whitelisted by cardholder |
Mandatory 3-D Secure Information
Some 3-D Secure information is mandatory and must be provided using the following threeDSOptions field or preferably using the associated standard integration field, in brackets, apart from the very rare circumstances where the two must have different values.
If this mandatory information is not available, then 3-D Secure will fail.
The following information is mandatory:
requestorName(merchantName) default stored on filerequestorURL(merchantWebsite) default stored on filemerchantCategoryCode(merchantCategoryCode) default stored on filebrowserIPAddress(deviceIpAddress)browserUserAgent(deviceIdentity)browserAcceptHeader(deviceAcceptContent)browserLanguage(deviceAcceptLanguage)
If the browserJavaScriptEnabled (deviceCapabilites) field is provided and indicates that JavaScript is enabled on the Cardholder’s browser, then the following information is also mandatory:
browserScreenColourDepth/browserScreenColorDepth(deviceScreenResolution)browserScreenWidth(deviceScreenResolution)browserScreenHeight(deviceScreenResolution)browserTimeZone(deviceTimeZone)
From 12 August 2024, for Visa transactions, the cardholderName (customerName) AND either the cardholderEmail (customerEmail) OR cardholderHomePhone (customerPhone) fields are mandatory.