Skip to main content

3DS Device Fingerprinting

Associating Client Browser Attributes with a 3DS Transaction ID.

Device fingerprinting is the association of client browser attributes with a specific transaction. This fits into the 3DS flow prior to a 3DS Authentications call. Device fingerprinting can be used within the PCI, PCI w/ CVV, or CVV Only modes of the TokenEx iFrame or built into your own checkout workflow.

When device fingerprinting is used, the authentication request will also include information about the cardholder’s browser. Although this may seem like duplicative work, the device fingerprint is obtained via a script provided by the ACS, while the browser data in the authentication request comes from the merchant. The ACS then looks for a match by comparing the device fingerprint with the browser data from the authentication request. Since the browser information is retrieved through remote JavaScript calls, it is recommended to gather the required browser data for the authentication request simultaneously with the device fingerprinting.

TokenEx iFrame​

The iFrame configuration object has three optional fields:

PropertyTypeDescription
use3DSbooleanTriggers device fingerprinting process
threeDSMethodNotificationUrlstringFully-qualified endpoint to receive notification following Device Fingerprinting. Required if use3DS is true
enforceLuhnCompliancebooleanTrue or False. If omitted, defaults to true. Set to False to bypass luhn checks in PCI or PCI w/ CVV modes. Co-Branded 3DS test cards are not luhn compliant. Has no effect in CVV Only Mode, because no PAN is entered in that mode.

The API key used to generate the authenticationKey must have the 3DS permission enabled. Contact Support to enable this permission.

When the PAN is tokenized, a SupportedVersions call is processed in the background. That SupportedVersions response is included in the Tokenize response as ThreeDSecureResponse. If the ThreeDSecureResponse has a threeDSMethodUrl, device fingerprinting can be performed and the browser attributes are associated with the ThreeDSecureResponse's threeDSServerTransID. If device fingerprinting can be performed, a hidden iframe is added to the same container housing the existing PAN iframe. The hidden iframe loads a script which associates the browser attributes with the threeDSServerTransID and then sends a base64 encoded notification to the threeDSMethodNotificationUrl.

The threeDSServerTransID should then be used within the ThreeDSecure/Authentications request in the ServerTransactionId field and the ACS will take the browser attributes into account when determining whether to issue a challenge.

Success Example​

A successful device fingerprinting will generate an iFrame Notice event, the tokenize response will have a threeDSecureResponse containing a threeDSMethodUrl, and a notification will be sent to the threeDSMethodNotificationUrl. Upon receipt of the notification, include MethodCompletionIndicator as 1 (successful) in the Authentications request.
If a notification is not received within 10 seconds of the TokenEx iFrame notice indicating device fingerprinting success, an unknown issue has occurred in the client's browser and the MethodCompletionIndicator should be included as 2 (not successful) in the Authentications request.

{ "type": "3DS Device Fingerprinting", "success": true }

Failure Example​

When device fingerprinting is not supported for a PAN or when another error occurs, a notice will be generated and the tokenize response's threeDSecureResponse will contain the error response. If the Tokenize response's threeDSecureResponse contains a value for threeDSMethodURL, set the Authentication request's MethodCompletionIndicator as 2 (device fingerprinting did not successfully complete); if threeDSecureResponse.threeDSMethodURL is not present, then set MethodCompletionIndicator to 3 (device fingerprinting URL is unavailable).

{"type":"3DS Device Fingerprinting","success":false}

CVV Only Mode​

CVV Only Mode operates on an existing token, so there is no tokenization event to trigger the SupportedVersions call. Instead, when use3DS is true the SupportedVersions call is processed automatically when the iFrame loads, using the token from the configuration object. The call is non-blocking — the CVV input renders immediately and remains usable regardless of the 3DS outcome.

Because there is no tokenize response in this mode, the SupportedVersions response is delivered through a dedicated 3DS event raised before device fingerprinting begins. The threeDSServerTransID is in threeDSecureResponse[0].

JavaScript
iframe.on("3DS", function (data) {
  // data.threeDSecureResponse    — the SupportedVersions results
  // data.recommended3dsVersion   — the highest supported 3DS version of the three servers
  // data.referenceNumber         — TokenEx reference number for the request
  var transId = data.threeDSecureResponse[0].threeDSServerTransID;
});

If the threeDSecureResponse has a threeDSMethodUrl, device fingerprinting proceeds exactly as described above: a hidden iframe associates the browser attributes with the threeDSServerTransID, a base64 encoded notification is sent to the threeDSMethodNotificationUrl, and an iFrame Notice event reports the outcome ({ "type": "3DS Device Fingerprinting", "success": true } or "success": false). The success and failure guidance above applies unchanged, with the 3DS event taking the place of the tokenize response: include MethodCompletionIndicator as 1 (successful) upon receipt of the notification, 2 (not successful) if no notification arrives within 10 seconds, or 3 (unavailable) if threeDSMethodURL is not present.

use3DS in CVV Only Mode still requires a threeDSMethodNotificationUrl; omitting it raises an error event ("Invalid Config Object") and the iFrame does not load.

See CVV Only Mode Configuration for a complete configuration example.

Outside the TokenEx iFrame​

When a checkout flow does not include the TokenEx iFrame or more control is needed, follow the below steps to add device fingerprinting to the page.

  1. Execute an API call to ThreeDSecure/SupportedVersions. If device fingerprinting is supported by the card issuer, the threeDSecureResponse will contain a threeDSMethodURL. Retrieve the threeDSMethodURL and the threeDSServerTransID from the response. If a threeDSMethodURL is not present, include MethodCompletionIndicator as 3 (unavailable) in the ThreeDSecure/Authentications request.

  2. Post a form to the threeDSMethodURL. The form parameter is threeDSMethodData. The content of that parameter should be a base64-encoded json object containing the threeDSServerTransID and an endpoint to receive a notification (steps 2a and 2b below) when device fingerprinting is completed. A script will be returned.

    {
      "threeDSMethodNotificationURL": "https://merchant-defined-webhook.merchant.com",
      "threeDSServerTransID": "52329f00-7951-4572-9432-356298fc300c"
    }

  3. Load that script into a hidden iframe within the customer's browser. This script (example above) will retrieve miscellaneous browser attributes of the card issuer's choice. The response to the above script is another script (example below) which upon execution will post to the merchant-defined threeDSMethodNotificationURL from Step 2a's JSON above.

    <script>
      document.addEventListener("DOMContentLoaded", function () {
        var form = document.createElement("form");
        form.method = "POST";
        form.action = "https://merchant-defined-webhook.merchant.com";
        form.enctype = "application/x-www-form-urlencoded";
        form.appendChild(createInput("threeDSMethodData", "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tZXJjaGFudC1kZWZpbmVkLXdlYmhvb2subWVyY2hhbnQuY29tIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI0ZjBiMTYyMS1kOTUwLTQyYzgtYmRlMS02ZDc2MGZmNzQ4NjgifQ=="));
        document.body.appendChild(form);
        form.submit();
        document.body.removeChild(form);
      });

      function createInput(name, value) {
        var result = document.createElement("input");
        result.name = name;
        result.value = value;
        return result;
      }
    </script>

  4. Upon receipt of the notification, include MethodCompletionIndicator as 1 (successful) in the Authentications request. If the notification is not received within 10 seconds of the script execution in Step 3, close the hidden iframe and include MethodCompletionIndicator as 2 (not successful) in the Authentications request.

The threeDSServerTransIDshould then be used within the ThreeDSecure/Authentications request in the ServerTransactionId field and the ACS will take the browser attributes into account when determining whether to issue a challenge.

PCI DSS 4.0 Requirements for Payment Page Scripts

While the PCI DSS 4.0 Requirement 6.4.3 to inventory and verify integrity of scripts executed on a payment page goes into effect on the 31st of March 2025, the scripts performing 3DS functionality are not subject to that requirement. More information can be found on the PCI SSC website.

Last updated on