3-D Secure authentication is an additional fraud prevention scheme that is on all e-commerce card transactions processed by the Gateway, where supported by the Acquirer.

It allows the Cardholder to assign a password to their card that is then verified whenever a transaction is processed through a site that supports the use of the scheme. The addition of password protection allows extra security on transactions that are processed online.

3-D Secure stands for Three Domain Secure. There are 3 parties that are involved in the 3-D Secure process:

The company from which the purchase is being made.
The Acquiring Bank (the bank of the company)
VISA and Mastercard (the card issuers themselves)

The gateway supports 3-D Secure as implemented by Visa, Mastercard and American Express and marketed under the brand names of Verified by VISA (VBV), Mastercard Secure Code (MSC) and American Express (SafeKey). Implementations by JCB (J/Secure) and DCI (ProtectBuy) are not currently supported.

3-D Secure is also the only fraud prevention scheme available that offers you liability cover for transactions that are verified by the checks. This provides additional protection for transactions using the scheme as distinct from those that do not.

The 3-D Secure preferences can be configured per Merchant Account within the Merchant Management System (MMS). These preferences can be overridden per transaction by sending one of the preference fields documented in section 5.5.1, which hold a comma separated list of the check responses that should be allowed to continue to completion. Responses not in the list will result in the transaction being declined with a responseCode of 65803 (3DS_NOT_AUTHENTICATED).

The Gateway supports both 3-D Secure version 1 and version 2 and will use the highest version available. Version 2 is also commonly known as EMV 3-D Secure.

3-D Secure is not available with all Acquirers and must be enabled on your Merchant Account before it can be used. Please contact support to find out whether your Acquirer supports it and if it can be enabled on your Merchant Account.

3-D Secure is supported by the Hosted and Direct Integrations. It is not supported by the Batch Integration.

5.2 Benefits and Limitations

5.2.1 Benefits

The results are available immediately and returned as part of the transaction.

The checks can be managed independently allowing you the utmost control over how the results are used.

The checks can be configured to decline the transaction automatically, where required.

If authentication is completed, liability for any subsequent fraud-related chargeback on that transaction shifts from you to the card issuer (but note the limitations below and check your Acquirer’s Terms and Conditions fully on this point).

There are no extra Gateway costs for using 3-D Secure. Your Acquirer may charge to add this onto your business account; however, you may also find that your transaction charges are lower as a result of using 3-D Secure.

Fully configurable within the Merchant Management System (MMS).

5.2.2 Limitations

Authenticated 3-D Secure transactions do not guarantee a liability shift and chargebacks can still occur. This is decided at the discretion of your Acquirer, with whom you should check its policy.

The gateway does not support 3-D Secure for JCB or Diner’s club cards.

3-D Secure transactions require a browser in order to display the Customer authentication dialog.

5.3 Hosted Implementation

If your Merchant Account is set up for 3-D Secure, the Hosted Payment Page will automatically attempt to display the 3-D Secure authentication page for the Customer’s bank.

The 3-D Secure authentication form is designed and controlled by the Customer’s Issuing bank and will display the Merchant Account name and any website address added when the account was onboarded. You can change the displayed name and website address by sending the merchantName and/or merchantWebsite request fields. Any merchantWebsite must be a fully qualified URL containing at least the scheme and host components.

For 3-D Secure version 2 you may also pass additional information about the transaction and Cardholder, using the threeDSOptions field as documented in section 5.5.4. This extra information can help the Issuer decide on whether a challenge is required. This version also requires your Merchant Account to be configured with your Merchant Category Code (MCC). This value can be configured in the Merchant Management System (MMS) or provided using the merchantCategoryCode or threeDSOptions request fields.

If you would like an example of a 3-D Secure Hosted Integration, please refer to our sample code appendix A-22.1.

For backward compatibility, the Hosted Integration will currently return the legacy 3-D Secure API response fields as documented in Appendix A-5 if it performs 3-D Secure version 1.

If 3-D Secure version 2 is used or one of the latest API 3-D Secure request, response or any of the device fields are used in the request, then it will return the latest API response fields as documented in section 5.6.2. (Note: response and device fields will be ignored in any request but will cause it to switch response format.)

To switch to always using the latest API response fields we highly recommend you pass in one of the following fields: threeDSPolicy, threeDSOptions or initiator.

5.4 Direct Implementation

If your Merchant account is set up for 3-D Secure, the Gateway will require further authentication details provided by the 3-D Secure system.

The 3-D Secure authentication form is designed and controlled by the Customer’s Issuing bank and will display the Merchant Account name and any website address added when the account was onboarded. You can change the displayed name and website address by sending the merchantName and/or merchantWebsite request fields. Any merchantWebsite must be a fully qualified URL containing at least the scheme and host components.

For 3-D Secure version 2 you must also provide details about the Cardholder’s device, using the fields documented in section 17.7 or using the associated options in the threeDSOptions field as documented in section 5.5.3. You may also use the threeDSOptions field to pass additional information about the transaction and Cardholder, which can help the Issuer decide on whether a challenge is required. This version also requires your Merchant Account to be configured with your Merchant Category Code (MCC). This value can be configured in the Merchant Management System (MMS) or provided using the merchantCategoryCode or threeDSOptions request fields.

The direct integration uses two complex fields to pass data between the 3-D Secure Access Control Server (ACS) and the Gateway. The threeDSRequest field will be provided by the Gateway and is a record whose name/value properties must be sent via a HTTP POST request to the ACS usually via means of a hidden HTML form you have rendered in Cardholder’s browser and then submitted using JavaScript. The corresponding threeDSResponse field should be returned to the Gateway and must be a record containing name/value properties taken from the HTTP POST received from the ACS when it redirects the Cardholder’s browser back to your threeDSRedirectURL on completion of any challenge.

Note that the contents of the threeDSRequest and threeDSResponse fields are formatted using the record format detailed in section 1.7.8 and their contents should be regarded as opaque and all name/value pairs received from the Gateway must be sent to the ACS, and vice versa. The Gateway does not currently support these fields to be provided in the serialised record format.

If you would like an example of a 3-D Secure Direct Integration, please refer to our sample code appendix A-22.2.

5.4.1 Initial Request (Verify Enrolment)

If no 3-D Secure authentication details are provided in the initial request, the Gateway will determine if the transaction is eligible for 3-D Secure by checking whether the card is enrolled in the 3-D Secure scheme.

If the Gateway determines that the transaction is not eligible for 3-D Secure, then it will continue to process it as a normal transaction without 3-D Secure, unless the threeDSRequired request field indicates that the transaction should be aborted instead.

To support 3-D Secure, you must pass the threeDSRedirectURL field in the initial request. This field must contain the complete URL to a web page on your server that the 3-D Secure Access Control Server (ACS) will HTTP POST the authentication results back to, when the authentication has been completed.

If the Gateway determines that the transaction is eligible, it will respond with a responseCode of 65802 (3DS AUTHENTICATION REQUIRED) and included in the response will be a threeDSReqest containing data that should be sent to the ACS at the threeDSURL using a HTTP POST request. The response will also contain a threeDSRef that can be used to continue the transaction when the authentication has been completed.

5.4.2 Continuation Request (Check Authentication and Authorise)

On completion of the 3-D Secure authentication the ACS will send the challenge results to the threeDSRedirectURL provided in the initial request using a HTTP POST request. The contents of this POST request should be returned to the Gateway unmodified in the threeDSResponse field together with the threeDSRef received in the initial response. This new request will check the authentication results and either response with the details for a further challenge, send the transaction to the Acquirer for approval or abort the transaction depending on the authentication result and your preferences, either sent in the threeDSCheckPref field or set in the Merchant Management System (MMS).

5.4.3 Multiple Challenges and Frictionless Flow

The API supports the issuing of multiple challenges where the continuation request may indicate the requirement to perform another challenge by responding with a responseCode of 65802 (3DS AUTHENTICATION REQUIRED) and including a further threeDSReqest, threeDSURL and threeDSRef. When this happens, these further challenge details should be treated the same as the first and POSTed to the ACS.

For 3-D Secure version 1, a single challenge is performed. However, for version 2, there may be zero, one or two challenges.

With 3-D Secure version 2, an initial device fingerprinting method might have to be invoked on the ACS, the results of which are used to determine whether the Cardholder must complete a challenge or whether a frictionless flow can be achieved where the transaction can continue unchallenged.

5.4.4 Cardholder Challenge

The Cardholder challenge takes place with the Cardholder’s browser, usually within an IFRAME embedded on the payment form. To start the challenge, the IFRAME should contain a HTML FORM with hidden INPUT fields storing the name/value pairs returned in the threeDSRequest record. JavaScript should then be used to submit the form automatically, causing the form data to be sent via a HTTP POST to the threeDSURL.

The IFRAME should be of sufficient size to display the ACS challenge form. For 3-D Secure version 1, this is a fixed size of 390×400 pixels. However, version 2 allows different sizes to be specified giving the Merchant more flexibility in the design of its payment form. The required size can be set using the ‘challengeWindowSize’ option, passed in the threeDSOptions field in the initial request.

5.4.5 Device Fingerprinting Challenge

The device fingerprinting method invocation is handled in the same way as a normal Cardholder challenge, except that it can be done silently in a hidden IFRAME, invisible to the normal payment flow. This silent device fingerprinting method request can be determined by the presence of a threeDSMethodData element in the threeDSRequest record (this is one time when the normally opaque data does need to be checked).

This method should take no longer than 10 seconds and therefore if the ACS has not POSTed the results back within 10 seconds then the browser can stop waiting and the transaction can be continued as normal but the threeDSResponse field should be returned indicating the timeout by including a threeDSMethodData element with the value of ‘timeout’, for example, “threeDSResponse[threeDSMethodData]=timeout”

5.4.6 External Authentication Request

You can choose to obtain the 3-D Secure authentication details from a third-party, in which case they should provide them as part of a standard request. If the Gateway receives valid third-party authentication details, then it will use those and not attempt to contact the 3-D Secure system itself.

5.5 Request Fields

5.5.1 Initial Request (Hosted and Direct Integration)

These fields should be sent in addition to basic request fields in section 2.1.

Field Name

merchantName

Mandatory?

No ¹

Description

Merchant name to use on 3DS challenge form.

Field Name

merchantWebsite

Mandatory?

No ¹

Description

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.

Field Name

merchantCategoryCode

Mandatory?

No ¹

Description

Merchant category code (3DS v2 only).

Field Name

threeDSRequired

Mandatory?

No ¹

Description

Is 3DS required for this transaction?

Possible values are:

N – 3DS is not required.
Y – Abort if 3DS is not enabled.

Field Name

threeDSCheckPref

Mandatory?

No ¹

Description

List of threeDSCheck response values that are to be accepted, any other value will cause the transaction to be declined. Value is a comma separated list containing one or more of the following values: ‘not known', 'not checked', ' not authenticated', 'attempted authentication', 'authenticated’.

Field Name

threeDSRedirectURL

Mandatory?

Yes ²

Description

A URL on the Merchant’s server to which the ACS can POST the challenge results, thus redirecting the challenge IFRAME to this page.

Field Name

threeDSOptions

Mandatory?

No ³

Description

Record containing 3DS options that can be used by the ACS for advance fraud checking. Refer to section 5.5.3 for further details.

Field Name

threeDSPolicy

Mandatory?

No ¹

Description

3DS Policy used (refer to Appendix A-18.3)

Field Name

threeDSVersion

Mandatory?

No ¹

Description

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.

Field Name

scaExemption

Mandatory?

No ¹

Description

An SCA exemption can be used to request that a frictionless flow is preferable when using 3DS v2. Refer to Appendix A-18.3 for further details.

1 Overrides any Merchant Account setting configured via the Merchant Management System (MMS).

2 Not required for Hosted Integration

3 Some browser configuration options are mandatory if the corresponding device detail fields are not provided

5.5.2 External Authentication Request (Direct Integration)

These fields should be sent in addition to basic request fields from section 2.1.

Field Name

threeDSEnrolled

Mandatory?

If 3DS enabled

Description

The 3DS enrolment status for the credit card. Refer to appendix A-3 for details.

Possible values are:

Y – Enrolled.
N – Not enrolled.
U – Unable to verify if enrolled (3DS v1 only).
E – Error verifying enrolment (3DS v1 only).

Field Name

threeDSAuthenticated

Mandatory?

If 3DS enrolled

Description

The 3DS authentication status for the credit card. Refer to appendix A-3 for details.

Possible values are:

Y – Authenticated.
A – Attempted to authenticate.
N – Not authenticated.
I – Information only (3DS v2 only).
U – Unable to authenticate.
E – Error checking authentication.

Field Name

threeDSXID

Mandatory?

If 3DS authenticated

Description

The unique identifier for the transaction in the 3DS system.

Field Name

threeDSECI

Mandatory?

If 3DS authenticated

Description

The Electronic Commerce Indicator (ECI).

Field Name

threeDSCAVV

Mandatory?

If 3DS authenticated

Description

The Cardholder Authentication Verification Value (CAVV).

Note: 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.

5.5.3 Continuation Request (Direct Integration)

These fields may be sent alone1.

Field Name

threeDSRef

Mandatory?

Yes

Description

The value of the threeDSRef field in the initial Gateway response.

Field Name

threeDSResponse

Mandatory?

Yes

Description

The data POSTed back from the ACS when the challenge has completed.

1 Note: 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. The message does not need to be signed. However, you can send any of the normal request fields to modify or supplement the initial request. 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).

5.5.4 3D Secure 2 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 version 2 experience or to help the ACS decide if a challenge is required. There are currently no options supported for 3-D Secure version 1.

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 details1, 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 detailed in section 1.7.8.

Option Name

accountAgeIndicator

Mandatory?

Description

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

Option Name

accountChangeDate

Mandatory?

Description

Date that the cardholder's account with the 3DS Requestor was last changed. Accepted date format is YYYYMMDD.

Option Name

accountChangeIndicator

Mandatory?

Description

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

Option Name

accountDate

Mandatory?

Description

Date that the cardholder opened the account with the 3DS Requestor. Accepted date format is YYYYMMDD.

Option Name

accountDayTransactions

Mandatory?

Description

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

1 The Hosted Integrations Payment Page will ignore any browser options and use its own details.

Option Name

accountId

Mandatory?

Description

Identifier for any Cardholder’s account with the Merchant.

Option Name

accountPasswordChangeDate

Mandatory?

Description

Date that cardholder's account with the 3DS Requestor had a password change or account reset. Accepted date format is YYYYMMDD.

Option Name

accountPasswordChangeIndicator

Mandatory?

Description

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

Option Name

accountProvisioningAttempts

Mandatory?

Description

Number of account provisioning attempts in the last 24 hours.

Option Name

accountPurchaseCount

Mandatory?

Description

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

Option Name

accountType

Mandatory?

Description

Indicates the type of account.

Possible values are:

01 – Not applicable
02 – Credit
03 – Debit

Option Name

accountYearTransactions

Mandatory?

Description

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

Option Name

acquirerBIN

Mandatory?

Description

Acquirer bank identification number. (Default on file)

Option Name

acquirerCountryCode

Mandatory?

Description

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)

Option Name

acquirerMerchantID

Mandatory?

Description

Acquirer-assigned merchant identifier. (Default on file)

Option Name

acsChallengeMandatedIndicator

Mandatory?

Description

Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables.

Option Name

addressMatch

Mandatory?

Description

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

Option Name

authenticationIndicator

Mandatory?

Description

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

Option Name

billingAddressCity (customerTown)

Mandatory?

Description

The city of the address. Maximum length is 50 characters.

Option Name

billingAddressCountryCode (customerCountryCode)

Mandatory?

Description

The country of the address as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents.

Option Name

billingAddressLine1 (customerAddress)

Mandatory?

Description

The first line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

billingAddressLine2

Mandatory?

Description

The second line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

billingAddressLine3

Mandatory?

Description

The third line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

billingAddressPostcode (customerPostcode)

Mandatory?

Description

The ZIP or other postal code of the address. Maximum length is 16 characters.

Option Name

billingAddressState

Mandatory?

Description

The state or province of the address as an ISO 3166-2 country subdivision code. Maximum length is 3 characters.

Option Name

browserAcceptHeader (deviceAcceptContent)

Mandatory?

Yes ¹

Description

HTTP accept header sent from the Cardholder’s browser.

Option Name

browserIPAddress (remoteAddress)

Mandatory?

Yes ¹

Description

IP v4 address of the Cardholder’s browser.

Option Name

browserJavaEnabled (deviceCapabilities)

Mandatory?

Yes ¹

Description

Ability of the Cardholder’s browser to execute Java.

Possible values are2:

true – browser can execute Java
false – browser cannot execute Java

Option Name

browserJavaScriptEnabled (deviceCapabilities)

Mandatory?

Yes ¹

Description

Ability of the Cardholder’s browser to execute JavaScript.

Possible values are2:

true – browser can execute JavaScript
false – browser cannot execute JavaScript

Option Name

browserLanguage (deviceAcceptLanguage)

Mandatory?

Yes ¹

Description

The Cardholder’s browser language. The browser language as defined in IETF BCP 47.

Option Name

browserScreenColourDepth or browserScreenColorDepth (deviceScreenResolution)

Mandatory?

Yes ^1,3

Description

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.

Option Name

browserScreenHeight (deviceScreenResolution)

Mandatory?

Yes ^1,3

Description

The screen height of the Cardholder’s browser.

Option Name

browserScreenWidth (deviceScreenResolution)

Mandatory?

Yes ^1,3

Description

The screen width of the Cardholder’s browser.

Option Name

browserTimeZone (deviceTimeZone)

Mandatory?

Yes ¹

Description

The difference between UTC time and the cardholder's browser local time in minutes.

Option Name

browserUserAgent (deviceIdentity)

Mandatory?

Yes¹

Description

The User-Agent header provided by the Cardholder’s browser.

Option Name

cardholderEmail (customerEmail)

Mandatory?

Description

The Cardholder’s email address.

Option Name

cardholderHomePhone(customerPhone)

Mandatory?

Description

The Cardholder’s home phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”).

Option Name

cardholderMobilePhone (customerMobile)

Mandatory?

Description

The Cardholder’s mobile phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”).

Option Name

cardholderName (customerName)

Mandatory?

Description

Name of the Cardholder. Limited to the alphanumeric characters listed in EMV Book 4, Annex B.

Option Name

cardholderWorkPhone

Mandatory?

Description

The Cardholder’s work phone number specified in the following format: “+CountryCode Subscriber” (eg “+44 1234567899”).

Option Name

challengeWindowSize

Mandatory?

Description

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

Option Name

deliveryEmailAddress (deliveryEmail)

Mandatory?

Description

Email Address to which the merchandise was delivered for electronic delivery.

Option Name

deliveryTimeframe

Mandatory?

Description

Merchandise Delivery Timeframe.

Possible values are:

01 – Electronic Delivery
02 – Same day shipping
03 – Overnight shipping
04 – Two-day or more shipping

Option Name

giftCardAmount

Mandatory?

Description

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

Option Name

giftCardCount

Mandatory?

Description

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

Option Name

giftCardCurrencyCode

Mandatory?

Description

For prepaid or gift card purchase, the currency code of the card as an ISO 4217 3-digit code or its 3 letter equivalent.

Option Name

instalmentPaymentData or installmentPaymentData

Mandatory?

Description

Indicates maximum number of authorizations permitted for instalment payments. Value must be greater than 1.

Option Name

merchantCategoryCode (merchantCategoryCode)

Mandatory?

Description

Code describing the Merchant's type of business, product, or service.

Option Name

merchantCountryCode (countryCode)

Mandatory?

Description

Country code of the merchant as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents.

Option Name

merchantFraudRate

Mandatory?

Description

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

Option Name

merchantName (merchantName)

Mandatory?

Description

Merchant name.

Option Name

paymentAccountAge

Mandatory?

Description

Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. Accepted date format is YYYYMMDD.

Option Name

paymentAccountAgeIndicator

Mandatory?

Description

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

Option Name

preOrderDate

Mandatory?

Description

For a pre-ordered purchase, the expected date that the merchandise will be available. Accepted date format is YYYYMMDD.

Option Name

preOrderPurchaseIndicator

Mandatory?

Description

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

Option Name

priorAuthData

Mandatory?

Description

Data that documents and supports a specific authentication process.

Option Name

priorAuthMethod

Mandatory?

Description

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

Option Name

priorAuthTimestamp

Mandatory?

Description

Date and time in UTC of the prior cardholder authentication.Accepted date format is YYYYMMDDHHMM.

Option Name

priorReference

Mandatory?

Description

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

Option Name

recurringExpDate

Mandatory?

Description

This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD

Option Name

recurringFrequency

Mandatory?

Description

This field indicates the minimum number of days between authorizations.

Option Name

reorderItemsIndicator

Mandatory?

Description

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

01 – First time ordered
02 – Reordered

Option Name

reqAuthData

Mandatory?

Description

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.

Option Name

reqAuthMethod

Mandatory?

Description

Method used by the Cardholder to authenticate to the 3DS Requestor.

Option Name

reqAuthTimestamp

Mandatory?

Description

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

Option Name

requestorChallengeIndicator

Mandatory?

Description

Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Option Name

requestorID

Mandatory?

Description

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.

Option Name

requestorName

Mandatory?

Description

Directory server assigned 3DS Requestor identifier. (Default on file)

Option Name

requestorURL (merchantWebsite)

Mandatory?

Description

Directory server assigned 3DS Requestor name. (Default on file)

Option Name

secureCorporatePaymentIndicator

Mandatory?

Description

3DS Requestor website or customer care site.

Option Name

serverOperatorID

Mandatory?

Description

Indicates dedicated payment processes and procedures were used, potential secure corporate payment exemption applies.

Option Name

serverRefNumber

Mandatory?

Description

3DS Server identifier. (Default on file)

Option Name

shipAddressUsageDate

Mandatory?

Description

Assigned server reference number. (Default on file)

Option Name

shipAddressUsageIndicator

Mandatory?

Description

Date when the shipping address used for this transaction was first used with the 3DS Requestor. Accepted date format is YYYYMMDD.

Option Name

shipIndicator

Mandatory?

Description

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

Option Name

shipNameIndicator

Mandatory?

Description

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

Option Name

shippingAddressCity (deliveryTown)

Mandatory?

Description

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

Option Name

shippingAddressCountryCode (deliveryCountryCode)

Mandatory?

Description

The city of the address. The maximum length is 50 characters.

Option Name

shippingAddressLine1 (deliveryAddress)

Mandatory?

Description

The country of the address as an ISO 3166-1 3-digit code or its 2 or 3 letter equivalents.

Option Name

shippingAddressLine2

Mandatory?

Description

The first line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

shippingAddressLine3

Mandatory?

Description

The second line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

shippingAddressPostcode

Mandatory?

Description

The third line of the street address or equivalent local portion of the address. Maximum length is 50 characters.

Option Name

(deliveryPostcode)

Mandatory?

Description

The ZIP or other postal code of the address. Maximum length is 16 characters.

Option Name

shippingAddressState

Mandatory?

Description

The state or province of the address as an ISO 3166-2 country subdivision code. Maximum length is 3 characters.

Option Name

suspiciousAccountActivity

Mandatory?

Description

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

Option Name

transactionType

Mandatory?

Description

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

Option Name

whitelistStatus

Mandatory?

Description

Whitelist status. Possible values are:

Y – 3DS Requestor is whitelisted by cardholder
N – 3DS Requestor is not whitelisted by cardholder

1 The Hosted Integrations Payment Page will ignore any browser options and use its own details.

2 Boolean values must be sent as the strings ‘true’ or ‘false’ unless JSON serialisation is used (refer to section 1.7.8)

3 This value is not mandatory if the browser doesn’t support JavaScript.

Some 3-D Secure v2 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 v2 will fail and, when possible, fallback to using 3-D Secure v1 (refer to section 5.7.1 for more details on fallback).

The following information is mandatory:

requestorName (merchantName) default stored on file – also required for 3DSv1
requestorURL (merchantWebsite) default stored on file – also required for 3DSv1

merchantCategoryCode (merchantCategoryCode) default stored on file

browserIPAddress (remoteAddress)

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)

5.6 Response Fields

5.6.1 Challenge Response (Direct Integration)

These fields are returned when a 3-D Secure challenge is required and provide the information necessary for you to request the Access Control Server (ACS) perform that challenge.

These fields will be returned in addition to the request fields from section 5.5.1 and the basic response fields in section 2.2.

Field Name

threeDSEnabled

Returned?

Always

Description

Is 3DS enabled for this Merchant Account?

Possible values are:

N – Merchant Account is not enabled.
Y – Merchant Account is enabled.

Field Name

threeDSPolicy

Returned?

If available

Description

The unique identifier for the transaction in the 3DS system.

Field Name

threeDSVETimestamp

Returned?

If 3DS enabled

Description

The time the card was checked for 3DS enrolment and any initial challenge determined.

Field Name

threeDSEnrolled

Returned?

If 3DS enabled

Description

The 3DS enrolment status for the credit card. Refer to appendix A-3 for details.

Possible values are:

Y – Enrolled.
N – Not enrolled.
U – Unable to verify if enrolled (3DS v1 only).
E – Error verifying enrolment (3DS v1 only).

Field Name

threeDSRef

Returned?

If 3DS enabled

Description

Value to return in the continuation request.

Field Name

threeDSURL

Returned?

If 3DS enrolled

Description

The URL of the ACS to which the challenge data should be sent via a HTTP POST request from the Cardholder’s browser.

Field Name

threeDSRequest

Returned?

If 3DS enrolled

Description

Record containing the name/value pairs that should be sent to the ACS via HTTP POST request from the Cardholder’s browser.

5.6.2 Final Response (Hosted and Direct Integration)

These fields are returned when the 3-D Secure stage has completed, and no further challenge is required.

These fields will be returned in addition to the request fields from section 5.5.1; any continuation request fields from section 5.5.3; any challenge response fields from section 5.6.1; and the basic response fields in section 2.2.

Field Name

threeDSEnabled

Returned?

Always

Description

Is 3DS enabled for this Merchant Account?

Possible values are:

N – Merchant Account is not enabled.
Y – Merchant Account is enabled.

Field Name

threeDSPolicy

Returned?

If available

Description

3DS Policy used (refer to Appendix A-18.3)

Field Name

threeDSXID

Returned?

If 3DS enabled

Description

The unique identifier for the transaction in the 3DS system.

Field Name

threeDSVETimestamp

Returned?

If 3DS enabled

Description

The time the card was checked for 3DS enrolment and any initial challenge determined.

Field Name

threeDSEnrolled

Returned?

If 3DS enabled

Description

The 3DS enrolment status for the credit card. Refer to appendix A-3 for details.

Possible values are:

Y – Enrolled.
N – Not enrolled.
U – Unable to verify if enrolled (3DS v1 only).
E – Error verifying enrolment (3DS v1 only).

Field Name

threeDSCATimestamp

Returned?

If 3DS enrolled

Description

The time the last challenge was checked.

Field Name

threeDSAuthenticated

Returned?

If 3DS enrolled

Description

The 3DS authentication status for the credit card. Refer to appendix A-3 for details.

Possible values are:

Y – Authenticated.
A – Attempted to authenticate.
N – Not authenticated.
R – Reject transaction
I – Information only (3DS v2 only).
U – Unable to authenticate.
E – Error checking authentication.

Field Name

threeDSECI

Returned?

If 3DS authenticated

Description

This contains a two-digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorisation message. This value indicates to the processor that the Customer data in the authorisation message has been authenticated. The data contained within this property is only valid if the threeDSAuthenticated value is Y or A.

Field Name

threeDSCAVV

Returned?

If 3DS authenticated

Description

This contains a 28-byte Base-64 encoded Cardholder Authentication Verification Value (CAVV). The data contained within this property is only valid if the threeDSAuthenticated value is Y or A.

Field Name

threeDSCAVVAlgorithm

Returned?

If 3DS authenticated

Description

The algorithm used to calculate the CAVV. This is return 3-D Secure version 1 only.

Field Name

threeDSDetails

Returned?

If 3DS authenticated

Description

Record containing further details about the 3-D Secure processing stage. Notable sub fields are:

version – 3-D Secure version used
versions – 3-D Secure versions available
fallback – whether fell back to version 1
fallbackReason – reason for fallback to version 1
psd2Region – whether payment in PSD2 jurisdiction

Field Name

threeDSErrorCode

Returned?

If 3DS error

Description

Any error response code returned by the ACS if there is an error in determining the card’s 3DS status.

Field Name

threeDSErrorDescription

Returned?

If 3DS error

Description

Any error response description returned by the ACS if there is an error in determining the card's 3DS status.

Field Name

threeDSResponseCode

Returned?

Always

Description

A numeric code providing the specific outcome of the 3-D Secure processing stage. Check threeDSResponseMessage for more details of any error that occurred. Refer to appendix A-1 for details.

Field Name

threeDSResponseMessage

Returned?

Always

Description

Any error message relating to the outcome of the 3-D Secure processing stage.

5.6.3 External Authentication Response (Direct Integration)

These fields will be returned in addition to the request fields from section 5.5.2 and the basic response fields in section 2.2.

Field Name

threeDSEnabled

Returned?

Always

Description

Is 3DS enabled for this Merchant Account?

Possible values are:
N – Merchant Account is not enabled.
Y – Merchant Account is enabled.

Note: 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.

5.6.4 Cardholder Information (Hosted and Direct Integration)

In the case of a frictionless flow, the card Issuer may sometimes wish to provide a message to the Cardholder. In this case, the threeDSResponseMessage will start with the text ‘Cardholder Info: ‘ and be followed by the message from the card Issuer.

5.7 Advanced Features

5.7.1 Fallback to Version 1

If a transaction supports both 3-D Secure version 1 and version 2 then it will always try to use version 2 and then if this fails it will automatically fallback to version 1. Fallback is always between major versions, the Gateway will not attempt version 2.2.0 and then fallback to 2.2.1, it would fall back to 1.0.2.

Any failure must be due to technical reasons only and never because the Cardholder entered their credentials incorrectly. A failure to provide the correct credentials is a successful 3-D Secure request and the transaction will continue with a threeDSAuthenticated value of ‘N’.

Failures could be due to invalid or missing request fields or options required by the higher 3-D Secure version or by external problems with the 3-D Secure system, such as communication errors with the Directory Server.

When fallback occurs, this will be indicated by the threeDSVersion response field and the fallback and fallbackReason entries in the threeDSDetails response field.

To help prevent fallback please ensure that you provide accurate details about the Cardholder’s device, using the threeDSOptions document in section 5.5.4 or the device fields documented in section 17.7. Also ensure any extra threeDSOptions provided are accurate along with any merchantName and merchantWebsite. You may find that you will need to provide values containing standard alpha-numeric characters only and do not include accented characters or other language specific characters. You must also ensure that the Merchant Account has a valid Merchant Category Code configured or that you pass a valid merchantCategoryCode field in your request.

5.7.2 PSD2 Strong Customer Authentication

3-D Secure can be used to provide the Strong Customer Authentication (SCA) required by the European Union’s Payment Services Directive 2 (PSD2).

For more details on how to use 3-D Secure to maintain PSD2 SCA Compliance please refer to Appendix A-18.3.