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.
You may also pass additional information about the transaction and Cardholder, using the threeDSOptions field as detailed in the 3-D Secure Options (Hosted and Direct Integration) section. This extra information can help the Issuer decide on whether a challenge is required.
Your Merchant Account must 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.
You will need to implement a callback page on your web server which the ACS can redirect the Cardholder’s browser to on completion of any challenges. You will need to provide the address of this page to the Gateway in your initial payment request via the threeDSRedirectURL field.
The direct integration uses two complex fields to pass data between the 3-D Secure Access Control Server (ACS) and the Gateway. The threeDSRequest is a record whose name/value properties must be sent via a HTTP POST request to the ACS. 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 callback page on completion of any challenge.
Note that the contents of the threeDSRequest and threeDSResponse fields are formatted using the record format 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.
Request Flow
Each step of the 3-D Secure flow is described below. At a high level it consists of a secure conversation between the Customer’s issuing bank and the Acquiring bank, facilitated by both the Merchant and the Gateway, in the form of several challenges. Each step of this conversation may contain a visible or invisible challenge. A 3-D Secure authentication form represents a visible challenge. An invisible challenge may be presented in the form of a Device Fingerprinting Method. The bank controls the number of challenges each transaction requires, and some transactions may be sufficiently trusted to require zero challenges. Because of this, your implementation will need to loop through multiple possible Continuation Requests, thus continuing the 3-D Secure process until you have received a message from the Gateway informing you that the 3-D Secure process has been completed.
1. You should send an initial request, to the Gateway containing the payment details, device details and any required threeDSOptions. This request must include your callback page, as described above, in the threeDSRedirectURL field.
2. If you receive a responseCode of 65802 then go to step 3 else display the results of the finished transaction as indicated by the responseCode and responseStatus as normal.
3. You must store the received threeDSRef value as it will be needed by the continuation request in step 6.
4. You should then send the contents of the received threeDSRequest to the 3-D Secure Access Control Server (ACS) at the received threeDSURL.
5. Once the ACS has completed the challenge then it will return the outcome back to your callback page as originally provided in step 1, as detailed in the Continuation Request (Check Authentication and Authorise) section.
6. You must then send a continuation request, to the Gateway containing the threeDSRef as stored in step 3 and a threeDSResponse containing the data received from the ACS in step 5.
7. As there can be multiple challenges you must now repeat the sequence from step 2.
If you would like an example of a 3-D Secure Direct Integration, please refer to our sample code.
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.
You must also provide details about the Cardholder’s device, using the fields detailed in the Device Information Fields section or using the associated options in the threeDSOptions field as detailed in the 3-D Secure Options (Hosted and Direct Integration) section. 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.
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 threeDSRef field, a threeDSReqest field and a threeDSURL field.
The threeDSRequest field is a record whose name/value properties must be sent, using a HTTP POST request, to the 3-D Secure Access Control Server (ACS) at the URL provided by the threeDSURL field. This is usually achieved via means of a hidden HTML input fields in a form rendered within an IFRAME displayed on the Cardholder’s browser and then submitted using JavaScript. The IFRAME must be of sufficient size to display the challenge screen, however, if the threeDSRequest contains a threeDSMethodData component, then the challenge is invisible, and a small hidden IFRAME can be used instead.
You must store the value of the threeDSRef field for use in the continuation request.
Continuation Request (Check Authentication and Authorise)
On completion of the 3-D Secure authentication the ACS will send the challenge results to you callback page, as originally specified using the threeDSRedirectURL field in the initial request.
The data will be received via means of a HTTP POST request and the contents of this POST request should be returned to the Gateway unmodified as name/value properties in the threeDSResponse field together with the threeDSRef received in the initial response.
This new request will check the authentication results and either respond 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).
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.
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.
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. The challenge form supports a limited number of different sizes, giving the Merchant more flexibility in the design of their payment form. The required size can be set using the ‘challengeWindowSize’ option, passed in the threeDSOptions field in the initial request
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”
External Authentication Request
You can choose to obtain the 3-D Secure authentication details from a third-party, in which case you 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 perform the 3-D Secure challenge flow.