3D Secure 2.0 Technical Integration Guide

Important: the following functionalities are not yet available on the PayOn test or live gateway!

3D Secure 2.0 Technical Integration Guide

COPYandPAY

For users of COPYandPAY, no additional effort is required compared to the current integration. ACI's widget and back-end integration will handle everything. The widget is collecting all necessary payment and browser data required for the risk-based authentication. Once the issuer decides that there is user authentication required, the authentication front-end will be rendered inside the widget.

The only thing you need to take care of, is that the necessary mandatory fields for 3DS 2.0 are sent in the API request.


OPP Server to server and standalone 3DS

For users who are integrating with the PayOn gateway via server to server will need to follow EMVCo's guidelines on the frontend integration. Please follow the steps described below:

1) Prepare your front-end and follow EMVCo's recommendation (see Section 4 "EMV 3-D Secure User Interface Templates, Requirements, and Guidelines" of the EMV® 3-D Secure Protocol and Core Functions Specification available here) on how the authentication window should be shown in the webshop (eg. in and iframe or in a lightbox).

2) Once the shopper clicks on the 'Pay' button (or similar button which initiates the payment), collect and send the following data about the shoppers browser via the server to server call to the PayOn gateway:

Field Opp Field name Description
Accept header customer.browser.acceptHeader HTTP accept header sent from the cardholder's browser.
Language customer.browser.language The cardholder's browser language.
Screen height customer.browser.screenHeight This field contains the total height of the cardholder's screen in pixels.
Screen width customer.browser.screenWidth This field contains the total width of the cardholder's screen in pixels.
Browser timezone customer.browser.timezone This field contains the cardholder's browser local timezone.
User agent customer.browser.userAgent This field contains the exact content of the HTTP User-Agent header.
IP address customer.browser.ipAddress IP address of the cardholder's browser.
Java enabled customer.browser.javaEnabled true/false - Ability of the cardholder's browser to execute Java.
Screen color depth customer.browser.screenColorDepth This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.
Authentication window size customer.browser.chellangeWindow

Size of the authentication iframe which will render the ACS authentication front-end to the shopper for interaction.

Please send an Integer between 1-5. The integer corresponds to one the following resolutions:

1 250 x 400
2 390 x 400
3 500 x 600
4 600 x 400
5 Full screen

3) Firstly, ACI will check which version of 3DS is supported by the issuer (1.0.x or 2.x)

4) If the version 2.x is returned, the PayOn gateway may return two values to the webshop: resultDetails.methodURL and resultDetails.methodData. Take resultDetails.methodData and POST it to resultDetails.methodURL from the cardholders browser. This will help the ACS retrieve data from the cardholders environment. Important note: if this step is executed or not, depends on the issuer.

5) After this, the PayOn backend will communicate with the scheme's directory server and determines if a cardholder authentication is required or not.

6) While the user is waiting for the result, the merchant website should display a graphical element (e.g. a progress bar) indicating to the cardholder that processing is ongoing (see here EMVCo's recommendation on what should the webshop display)

7) Once you receive the result from the PayOn gateway, 2 things can happen:

a) The risk-based authentication on the issuer side determined that the user doesn't have to go through the challenge workflow. In this case ACI will proceed with the authorization of the payment and the result returned to the merchant will be the result of the authorization. The payment workflow is done.

b) If the issuer decides that the shopper has to go through additional authentication, the PayOn gateway will return 3 fields that the webshop will need to include in a form to submit to the ACS: shopperResultURL, resultDetails.challengeRequest, resultDetails.sessionData.

Include the following form in the place (eg iframe) where the authentication interaction will happen, and submit it to the ACS:

<form name='downloadForm' action='ACSURL' method='POST'>
	<INPUT type='hidden' name='creq' value='resultDetails.challengeRequest'>
	<input type='hidden' name='threeDSSessionData'  value='resultDetails.sessionData'>
</form>
<script>
	window.onload = submitForm;
	function submitForm() { downloadForm.submit(); }
</script>

This will post the necessary data to the ACS and in return the ACS will render the authentication window in the iframe. The shopper completes the necessary authentication steps with their bank, and after it's done, the ACS will post the result to ACI. If the result is successful, the workflow will continue with the authorization, otherwise ACI will return an error response indicating the declined authorization.

Important note about compatibility with 3DS 1.0

In case the issuer responds to ACI in the initial call that 3DS 2.0 is not supported, 3DS 1.0 workflow will apply. This means, that in step 5 ACI will return only the shopperResultURL with the ACS URL for the authentication. The webshop should handle it as a 3DS 1.0 transaction, and just redirect the shopper to this URL, or call this URL in an iframe.

Fields required for 3DS 2.0

Please note that in order to have a better rate of successful risk-checks during the risk based authentication, it is recommended to send as many fields as possible. This will positively affect the number of frictionless flows.

Source is the cardholder or cardholder's environment

Field name Mandatory/Optional Source when using the widget Source when integrating via Server-to-Server API
card.expiryMonth Mandatory Cardholder (via widget) Cardholder (via API)
card.expiryYear Mandatory Cardholder (via widget) Cardholder (via API)
card.number Mandatory Cardholder (via widget) Cardholder (via API)
billing.city Mandatory Cardholder (via widget or API) Cardholder (via API)
billing.country Mandatory Cardholder (via widget or API) Cardholder (via API)
billing.street1 Mandatory Cardholder (via widget or API) Cardholder (via API)
billing.postcode Mandatory Cardholder (via widget or API) Cardholder (via API)
customer.email Mandatory Cardholder (via widget or API) Cardholder (via API)
customer.workPhone Mandatory Cardholder (via widget or API) Cardholder (via API)
customer.givenName Mandatory Cardholder (via widget or API) Cardholder (via API)
customer.surname Mandatory Cardholder (via widget or API) Cardholder (via API)
amount Mandatory Payment (via API) Payment (via API)
currency Mandatory Payment (via API) Payment (via API)
shipping.city Optional Cardholder (via widget or API) Cardholder (via API)
shipping.country Optional Cardholder (via widget or API) Cardholder (via API)
shipping.street1 Optional Cardholder (via widget or API) Cardholder (via API)
shipping.street2 Optional Cardholder (via widget or API) Cardholder (via API)
shipping.postcode Optional Cardholder (via widget or API) Cardholder (via API)
shipping.state Optional Cardholder (via widget or API) Cardholder (via API)
billing.street2 Optional Cardholder (via widget or API) Cardholder (via API)
billing.street2 Optional Cardholder (via widget or API) Cardholder (via API)
billing.state Optional Cardholder (via widget or API) Cardholder (via API)
customer.phone Optional Cardholder (via widget or API) Cardholder (via API)
customer.mobile Optional Cardholder (via widget or API) Cardholder (via API)
customer.browser.acceptHeader Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.language Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenHeight Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenWidth Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.timezone Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.userAgent Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.ipAddress Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.javaEnabled Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenColorDepth Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.chellangeWindow Optional Automatically collected by the widget Merchant should collect and send via API

Source is the merchant

Field name Mandatory/Optional Comment
Merchant category code Mandatory
Merchant country code Mandatory
Merchant name Mandatory Merchant name assigned by the Acquirer or Payment System.
Merchant ID Mandatory Acquirer-assigned Merchant identifier.
Requestor ID Mandatory DS assigned 3DS Requestor identifier.
Requestor Name Mandatory DS assigned 3DS Requestor name.
Requestor URL Mandatory Fully qualified URL of 3DS Requestor website or customer care site.


Optional settings

Merchants have the possibility to set the preference of a transaction being challenged or not. This really is only a preference, and won't guarantee that the issuer will or will not request a challenge from the cardholder. It is up to the issuer if they consider the merchant's preference, and if they include it when they assess the risk of the transaction.

For example when a card is being stored for later use (eg. for One click checkout), a challenge may be requested by the merchant. In another example, there might be some regional mandates that certain transactions have to be challenged and the merchant should ask for a mandated challenge.

Send the field threeDSecure.challengePreference with one of the following values:

Value Challenge Preference Description
01 No preference The merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02 No challenge requested The merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03 Challenge requested: 3DS Requestor Preference The merchant prefers that the cardholder is authenticated by the issuer.
04 Challenge requested: Mandate The cardholder authentication is mandated (eg. by regional mandates)

The field threeDSecure.challengePreference is optional. If not sent, the value "01 - No preference" applies by default.