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:
Render a hidden HTML iframe in the Cardholder browser
Create a form with an input field named
threeDSMethodData
This field must contain the above JSON message, Base64-URL encoded
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"
.