3-D Secure Authentication
Quick Find
Go straight to the section you need.
1.0 Gateway Integration →
2.0 New Transactions →
3.0 Management Requests →
4.0 AVS/CV2 Checking →
5.0 3-D Secure Authentication →
11 Receipts and Notifications →
17 Advanced Data →
17.7 Device Information Fields
19 Gateway Wallet →
26 Digital Wallet Transactions →
Appendix
A-1 Response Codes
A-1.1 Authorisation Response Codes
A-2 AVS / CV2 Check Response Codes
A-3 Secure Authentication Data
A-4 3-D Secure Enrolment/Authentication Only
A-9 Duplicate Transaction Checking
A-10 Capture Delay
A-13 Sample Signature Calculation
A-14 Transaction Life cycle
A-14.1 Authorise, Capture and Settlement
A-15.2 Mail Order/Telephone Order (MOTO)
A-15.3 Continuous Authority (CA)
A-16 Payment Tokenisation
A-16.1 PREAUTH, SALE, REFUND, VERIFY requests
A-16.3 CANCEL or CAPTURE requests
A-16.5 SALE or REFUND Referred Authorisation requests
A-18 PSD2 SCA Compliance
A-18.1 Obtaining Strong Customer Authentication
A-18.3 Exemptions to Strong Customer Authentication
A-19 Hosted Payment Page Options
A-20 Integration Libraries
A-20.1 Gateway Integration Library
A-20.2 Hosted Payment Page Library
A-20.3 Hosted Payment Fields Library
A-21 Example HTTP Requests
A-22 Example Integration Code
A-23 Example Library Code
A-23.1 Gateway Integration Library
5.o 3-D Secure Authentication
5.1 Background
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
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Possible values are:
N – 3DS is not required.
Y – Abort if 3DS is not enabled.
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
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
Mandatory?
Description
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
Mandatory?
Description
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
Mandatory?
Description
Field Name
Mandatory?
Description
Field Name
Mandatory?
Description
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
Mandatory?
Description
Field Name
Mandatory?
Description
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
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – Changed during this transaction
02 – Less than 30 days
03 – 30-60 days
04 – More than 60 days
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
1 The Hosted Integrations Payment Page will ignore any browser options and use its own details.
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – Not applicable
02 – Credit
03 – Debit
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
Y – Shipping address matches billing address.
N – Shipping address does not match billing address
Option Name
Mandatory?
Description
Possible values are:
01 – Payment - default
02 – Recurring
03 – Instalment
04 – Add Card
05 – Maintain Card
06 – Verify Cardholder
07 – Billing Agreement
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are2:
true – browser can execute Java
false – browser cannot execute Java
Option Name
Mandatory?
Description
Possible values are2:
true – browser can execute JavaScript
false – browser cannot execute JavaScript
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are: 1, 4, 8, 15, 16, 24, 32, 48.
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – Electronic Delivery
02 – Same day shipping
03 – Overnight shipping
04 – Two-day or more shipping
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – Merchandise available
02 – Future availability
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – Frictionless authentication occurred by ACS
02 – Cardholder challenge occurred by ACS
03 – ACS verified
04 – Other issuer methods
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – First time ordered
02 – Reordered
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
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
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – This transaction
02 – Less than 30 days
03 – 30-60 days
04 – More than 60 days
Option Name
Mandatory?
Description
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
Mandatory?
Description
Possible values are:
01 – Account Name identical to shipping Name
02 – Account Name different than shipping Name
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Option Name
Mandatory?
Description
Possible values are:
01 – No suspicious activity has been observed
02 – Suspicious activity has been observed
Option Name
Mandatory?
Description
Possible values are:
01 – Goods/ Service Purchase
03 – Check Acceptance
10 – Account Funding
11 – Quasi-Cash Transaction
28 – Prepaid Activation and Load
Option Name
Mandatory?
Description
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
Returned?
Description
Possible values are:
N – Merchant Account is not enabled.
Y – Merchant Account is enabled.
Field Name
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
Possible values are:
N – Merchant Account is not enabled.
Y – Merchant Account is enabled.
Field Name
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
Field Name
Returned?
Description
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
Returned?
Description
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.