4.2. 3DS Method invocation

Note

Only used for browser authentication

The 3DS Method can be optionally used by issuers to gather browser fingerprints using JavaScript. This is done by loading a URL in a hidden iframe, before the authentication. This iframe will then execute some fingerprinting JavaScript, before POST’ing to the prespecified URL belonging to the requestor. The 3DS Method fingerprint result is tied to the authentication by the threeDSServerTransID.

If 3DS Method URL is included in the /preauth endpoint response, the 3DS method must be invoked as explained in this guide.

If threeDSMethodURL is not included in the /preauth response (ref. 2.1.0, 2.1.0), continue with the /auth endpoint and set 3DS Completion indicator to "U", to indicate that the 3DS Method was not available.

Initiating 3DS Method

Create a JSON object containing threeDSServerTransID from the preauth call and the callback URL you wish to receive the POST to in threeDSMethodNotificationURL:

{
 "threeDSServerTransID": "d461f105-1792-407f-95ff-9a496fd918a9",
 "threeDSMethodNotificationURL": "<Requestor callback URL>"
}

The procedure is as follows:

  1. Render a hidden HTML iframe in the Cardholder browser

  2. Create a form with an input field named threeDSMethodData

  3. This field must contain the above JSON message, Base64-URL encoded

  4. Post the form to the threeDSMethodURL, with the HTML iframe as a target

Example

Add an iframe to the users browser, here using JavaScript

let displayBox = document.getElementById('displayBox');

let iframe = document.createElement('iframe');
iframe.classList.add('hidden');
iframe.name = "threeDSMethodIframe";

displayBox.appendChild(iframe);

Resulting in the following html

<iframe name="threeDSMethodIframe" class="hidden"/>

Create a HTML form, that contains the input field:

<form class="" id="threeDSMethodForm">
  <input type="hidden" name="threeDSMethodData" id="threeDSMethodData"/>
</form>

This form can be submitted using the following JavaScript:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Generate the data object with required input values
let threeDSMethodData = {
  threeDSServerTransID: '<TRANS ID>',
  threeDSMethodNotificationURL: '<URL>'
}

// Get a reference to the form
let form = document.getElementById('threeDSMethodForm');

// 1. Serialize threeDSMethodData object into JSON
// 2. Base64-URL encode it
// 3. Store the value in the form input tag
// Notice: You have to define base64url() yourself.
// Warning: The Base64-URL value must not be padded with '='
document.getElementById('threeDSMethodData').value =
 base64url(JSON.stringify(threeDSMethodData));

// Fill out the form information and submit.
form.action = '<threeDSMethodURL>';
form.target = 'threeDSMethodIframe'; // id of iframe
form.method = 'post';
form.submit();

Completion

When the 3DS Method is finished, the hidden iframe will HTTP POST a form to the threeDSMethodNotificationURL.

The POST body will contain the value threeDSMethodData, which can used to identify the request. An example application/x-www-form-urlencoded body:

threeDSMethodData=eyJ0aHJlZURTTWV0aG9kRGF0YSI6ICJkNDYxZjEwNS0xNzkyLTQwN2YtOTVmZi05YTQ5NmZkOTE4YTkifQ

The value is Base64-URL encoded and decodes to:

{"threeDSServerTransID": "d461f105-1792-407f-95ff-9a496fd918a9"}

Continue the authentication with the /auth endpoint, setting 3DS Completion indicator to "Y".

Your system must be able to receive both padded and unpadded Base64-URL values, in the 3DS Method completion callbacks.

3DS Method failure

If the callback to threeDSMethodNotificationURL is not received within 10 seconds from the POST call, it has failed. Close the iframe and continue the authentication with the /auth endpoint, setting 3DS Completion indicator to "N".