Related topics

1. Introduction

The 3-D Secure protocol enables the cardholder to be identified during the purchasing process. The cardholder needs to be connected to the Internet during the identification process. Thus 3-D Secure does not work for call centre or recurring payments.

Visa has implemented the 3-D Secure protocol under the name Verified By Visa, MasterCard under the name SecureCode, JCB under the name J-Secure and American Express under the name SafeKey.

The principle of the integration of DirectLink with 3-D Secure is to initiate a payment in DirectLink mode and end it in e-Commerce mode if a cardholder authentication is requested.

This document describes the integration of the 3-D Secure protocol in DirectLink. For further information on DirectLink or e-Commerce, go to DirectLink or e-Commerce documentation.

2. 3-D transaction flow via DirectLink

The transaction flow involves the following steps:

You send us a DirectLink request for the transaction, containing a number of additional parameters (cf. Extra request parameters).

Our system receives the card number in your request and checks online whether the card is registered in the VISA/MasterCard/JCB/AmEx directory (registered means that identification is possible for the card number, i.e. the card is a 3-D Secure card).

If the cardholder is registered, the answer to the DirectLink request contains a specific payment status and html code that has to be returned to the customer to start the identification process (cf. Additional return fields). The block of html code will automatically start the identification process between the cardholder (customer) and his issuing bank.

The cardholder identifies himself on the issuing bank’s page.

Our system receives the identification response from the issuer.

If the identification was successful, our system will submit the actual financial transaction to the acquirer.

You receive the result of the global identification and online authorisation process via e-Commerce mode feedback channels.

Comments:

Whether the liability shift applies or not depends on your acquirer contract. Therefore, we recommend you to check the terms and conditions with your acquirer.

If the cardholder is not registered (in step 3), you will receive the standard DirectLink XML response containing the result of the online authorisation process.

To receive the exact payment status/error codes (in step 7), you need to implement the online or offline post-sale feedback as described in the e-Commerce documentation.

2.1 Extra request parameters

Apart from the standard DirectLink parameters, you also need to send the following information:

Field

Description

FLAG3D

Fixed value: ‘Y’

Instructs our system to perform 3-D Secure identification if necessary.

HTTP_ACCEPT

The Accept request header field in the cardholder browser, used to specify certain media types which are acceptable for the response. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. For example:
Accept: */*

HTTP_USER_AGENT

The User-Agent request-header field in the cardholder browser, containing information about the user agent originating the request. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. For example: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)

WIN3DS

Way to show the identification page to the customer. Possible values:

MAINW: display the identification page in the main window (default value).

POPUP: display the identification page in a pop-up window and return to the main window at the end.

POPIX: display the identification page in a pop-up window and remain in the pop-up window.

ACCEPTURL

URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised).

DECLINEURL

URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section).

EXCEPTIONURL

URL of the webpage to show the customer when the payment result is uncertain.

PARAMPLUS

Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.

COMPLUS

Field to submit a value you wish to be returned in the post-sale request or output.

LANGUAGE

Customer’s language, for example: “en_US”

Optional

TP

To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter. (go to e-Commerce: Dynamic template).

2.2 Additional return fields

If the cardholder is not registered, the normal DirectLink response is returned. If the cardholder is registered, the following (additional) fields will be returned:

Field

Description

STATUS

New value: “46” (waiting for identification)

HTML_ANSWER

BASE64 encoded html code to be added in the html page returned to the customer.

This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser.

This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value.

To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 DEcoded before it is included in the html page sent to the cardholder.

2.3 Comments

2.3.1 Test cards

You can use the following test cards to simulate a 3-D Secure registered card in our test environment:

Brand

Card number

Expiry date

Password

VISA

4000000000000002

Any date in the future

11111

MasterCard

5300000000000006

Any date in the future

11111

American Express

371449635311004

Any date in the future

11111

2.3.2 Incorrect identification

If a transaction is blocked due to incorrect identification, the transaction result will be:

Ingenico ePayments is the online and mobile commerce division of Ingenico Group. We connect merchants and consumers, enabling businesses everywhere to go further beyond today’s boundaries and creating the future of global commerce. As industry leaders since 1994, our innovative spirit drives us forward across all channels. We are the trusted partner of over 65,000 small and large merchants who rely on us to make payments easy and secure for their customers. With advanced data analytics, fraud management solutions and cross-border commerce expertise, we help merchants optimize their business and grow into new markets around the world.

Learn more

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.