API Reference

Introduction

3D Secure

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 unauthorized CNP transactions and protects the merchant from CNP exposure to fraud. This service is available in Canada as well as in USA.

Berkeley's implementation of 3D Secure allow our clients to take the advantage of risk-based authentication and liability shift that 3D Secure offers with the benefits of DirectSend real-time transactions.

📘

In order to call the 3DS endpoints a cardholder and financial account need to be created.

All versions of 3D Secure supports 'risk based authentication`. This is where the consumer's bank (the issuer) uses information gathered from the user as well as the user's device information to authenticate the user. If they are able to do so without soliciting additional info from the consumer this is considered 'risk based authentication' and the process continues seamlessly without additional input from the consumer

Step 1 - Tokenize card

Tokenize an existing card using the V1 or V2 tokenization endpoints

Step 2 - Create account holder

Create an account holder using https://developers.berkeleypayment.com/reference/createaccountholder-1

You will need the id of the response in the next step

Step 3 - Create financial account

This links the cardholder to the financial account. Use https://developers.berkeleypayment.com/reference/createfinancialaccount-1 passing the id from the Create account holder step into account_holder_id

You will need the id of the response in the next step, this the financial account token.

Step 4 - Authenticate browser

Call AuthenticateBrowser passing in the id from step 3 into the financial_account parameter.

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 5

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 6

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 7

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