Introduction

Three-D secure

This document outlines the 3DS workflow process on the service provider side as well as a guide for the Berkeley client facing API. This document serves both as internal documentation as well as a the basis for a client facing guide (see Berkeley 3DS section).


Berkeley 3DS

EMV® Three-Domain Secure (3DS) is a messaging protocol developed by EMVCo (Europay, Mastercard, Visa and some other card schemes) to enable consumers to authenticate themselves with their card issuer when making card-not-present (CNP) e-commerce purchases. The additional security layer helps prevent unauthorised CNP transactions and protects the merchant from CNP exposure to fraud. This service is available in Canada as well as in USA.

Step 1

Make the AuthenticateBrowser API request call

The first payment request creates the 3DS authentication transaction, giving us the required data to communicate with the ACS performing risk based authentication. When securing card payments in the browser, the response from the /authenticate/browser determines which ACS (bank or bank partner) does a risk assessment of the transaction. The data returned will be different for 1.0 and 2.0 responses.

  • The response should be used to setup the iFrame that will handle the device fingerprinting.
  • Key response fields:
    • method_url: This is the url used to gather device information.
    • three_ds_method_data: Base64 encoded json with the notificationUrl, transactionId to send to the ACS for device fingerprinting. This should be setup in a 1x1 iframe.
  • There are two types of responses.
    • Most cases, the 2.0 responses will have a method_url that indicates an iframe needs to be created for fingerprinting. Follow the next steps in order to move forward.
    • In rare occasions the response will return without a method_url. In that case, fingerprinting will not need to happen but instead, take the transaction ID and make the call straight to get the results.

Step 2

Device Fingerprinting

A URL and data is returned in the authenticate/browser. The URL is the where you will post the iframe and pass in the data that was given. This is the fingerprinting portion. The ACS will connect to the browser and extract meta data that will be cross referenced with the clients purchase history. Based on that information the transaction will be authenticated.

In your browser, you need to create a hidden iframe and POST with the appropriate content based on the protocol version you received in the previous call.

  • three_ds_method_data and method_url

🚧

Browser ONLY
This portion of the flow needs to happen in a browser. There is no other way around it.

Browser ONLY

This portion of the flow needs to happen in a browser. There is no other way around it.

<iframe id="somethingUnique" style="display:none">
    <html>
    <body>
        <form name="sendFingerprint" action="method_url" method="post">
            <input name="threeDSMethodData" value="three_ds_method_data" />
        </form>
    </body>
    <script type="text/javascript">
        setTimeout(function() {
            document.createElement('form').submit.call(document.sendFingerprint);
        }, 100);
    </script>
    </html>
</iframe>

Step 3

Make Get 3DS Status API call

After the fingerprinting is finished, a GET call will need to be made. The response returned will advise if the transaction got authenticated, not authenticated, or challenged.

📘

Your request to retrieve tokens can last up to 15 seconds. During that time, we continually listen for updates. Therefore, you will get the authentication results as soon as they are available!

  • Check for the status of the device fingerprinting with the ACS using the Get Status API request
  • Key response fields:
    • status: Current status of 3DS authentication.
    • acs_url: Fully qualified URL of the ACS to be used for the challenge.
    • creq: Base64 encoded CReq that needs to be sent to the ACS when the status is C (challenge required)
  • In the case that status is authenticated this is the final step for a successful authentication. The 3DS authentication id can be attached to an associated transaction request.

📘

Information

For the purposes of DirectPull transactions, the following properties are important

  • eci
  • authentication_value
  • id

You will need to pass the 3DS authentication id in the three_d_secure_id field of the DirectSend Create Pull Transaction

Step 4

Challenge Request

In case of status is challenge_required we know that the ACS requires a challenge. As such, there are a couple more steps to respond to a 2.0 challenge.

Open the Challenge Request URL in an iframe

From the previous response, we need to extract the acs_url and the creq properties.

In the browser, we will setup an iframe which sends the CReq to the ACS URL (similar to the device fingerprinting)

The ACS will then present a UI within that iframe for the user to complete.

Example of a ACS challenge iframe form:

<iframe id="anotherUniqueID" style="display:none">
    <html>
    <body>
        <form name="sendChallenge" action="https://acs-server-sandbox.3dsintegrator.com/v2/challenge/ui" method="post">
            <input name="creq" value="eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyNzljZjUwYy1lZjM2LTQzMTMtYjA0ZC05NGNlZGZhZWRmZDQiLCJhY3NUcmFuc0lEIjoiZDZmMTVhYWUtMmM5ZC00MzMzLWE5MjAtOTU0YmUwN2MwYzc2IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0=" />
        </form>
    </body>
    <script type="text/javascript">
        setTimeout(function() {
            document.createElement('form').submit.call(document.sendFingerprint);
        }, 100);
    </script>

    </html>
</iframe>

In 2.0, the challenge flow requires 2 iframe:

  • The initial browser fingerprinting for sending the three_ds_method_data
  • The challenge UI for sending the CReq and responding to the challenge

This is different from 1.0 . In 3DS version 1, only one iframe is required. When integrating, ensure that two separate iframes can be used!

Retrieving Results for a Challenge

After completing the challenge requests, we make another Get Status request.


Recurring Transactions

In general, for the very first transaction when a customer sets up a recurring payment, it is recommended that you establish a secure authentication by requesting a cardholder challenge (challenge_indicator = 03).  Any subsequent transactions are out of scope from the 3D Secure requirements.

❗️

Original 3-D Secure only provided chargeback protection against the first transaction whereas EMV 3DS protects all recurring transactions.
By applying 3D Secure to the first transaction or verification, you signal to the card issuer that you have established a mandate between you and your customer to charge their payment method for subsequent recurring payments as detailed in your terms and conditions. Such subsequent transactions are out of scope from PSD2 SCA requirements.

📘

Related pages

3DS Status Codes
3DS Test Cards
Test Cards