EMV® 3-D Secure

Overview

Strong Customer Authentication (SCA) is a set of rules that verify a cardholder's identity during online purchases to help prevent fraud. 3-D Secure is a specific implementation of SCA that is commonly used in online credit and debit card transactions.

3-D Secure provides an additional layer of authentication for merchants to ensure a purchase is from a legitimate cardholder. It helps to protect businesses from fraudulent disputes and comply with regulations by verifying the identity of the cardholder at the point of payment through the issuing bank.

EMV 3DS process

Frictionless flow

The frictionless flow allows issuers to approve a transaction without the need to interact with the cardholder. It utilises device biometrics to verify cardholder authenticity, providing a smoother transaction for the cardholder.

Challenge flow

If the issuer determines that further cardholder interaction is required to complete the authentication, the Frictionless Flow transitions into the Challenge Flow. The Challenge Flow is used to present a way of authenticating the cardholder using biometric signatures or secure credentials.

Setting up EMV 3DS

To authenticate all one-off payments (anything that is not recurring) using EMV 3DS you must do the following:

Step 1: Add a "tds" object to the request

Add a tds object added to the request, just like this one:

{
  "tds": {
    "is_active": true,
    "contact_url": "https://yourdomain.com/support",
    "redirect_url": "https://yourdomain.com/redirect",
    "webhook_url": "https://yourdomain.com/webhook"
  }
}

See below for a description of the fields in the tds request:

Step 2: We will return an authentication URL

When we receive your request, if the card being used to make the payment is enrolled for EMV 3DS we will return an authentication url. All you need to do is redirect the user to this url either via a full redirect or within an iframe, and we will complete the authentication process for you.

{
 "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
 "status": "tds_pending",
 "links": [
   {
     "rel": "self",
     "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7121717"
   },
   {
     "rel": "tds",
     "href": "https://auth.acquired.com/a7e3fde5-5b83-44f4-9915-782bc7121717"
   }
 ]
}

See below for a description of the fields in the authentication url request:

📘

Note

If the card is not enrolled for EMV 3DS, we will respond to let you know. We recommend not accepting these transactions as there is no liability shift provided for chargebacks when cards are not enrolled for 3DS.

Example response for cards not enrolled with EMV 3DS:

{
    "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
    "status": "tds_failed",
    "reason": "card_not_enrolled",
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7121717"
    }
  ]
}

Step 3: Handle the customer redirect

After the authentication is completed the cardholder will be returned to the redirect URL you set in the initial payment request.

In order for you to be able to present your customer with the updated transaction status, we will send a form POST to the redirect URL.

Example of a successful response:

"status":"success","transaction_id":{{transaction_id}},"order_id":{{order_id}},"timestamp":{{timestamp}},"hash":{{hash}}

Example of a tds_failed response:

"status":"tds_failed","transaction_id":{{transaction_id}},"order_id":{{order_id}},"timestamp":{{timestamp}},"reason":"low_confidence","hash":"{{hash}}

See below for a table of the keys and values that will be present:

Step 4: Validate the integrity of the form data

A hash value will be calculated every time a customer is navigated to the redirect_url used for the payment. This allows you to guarantee the authenticity of the data.

To do this, generate a new hash value and compare it to the returned hash value. If the hash values match then the data has not been altered and the origin and integrity of the data has been verified.

To calculate the hash value, you'll need to do the following:

1. Concatenate the parameters in this order: status . transaction_id . order_id . timestamp

executed1970f4e1-95da-4859-b275-e9ac83f05eb1your_unique_reference_11657183950

2. SHA256 encrypt the resulting string.

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007

3. Append your app_key value to the hash value of a string.

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007app_key

4. SHA256 encrypt the resulting string again.

4e7e127a6ab8e7c4d73100e0c959eb42e1d61adff6b641c6ea7e4690e44cbff0

5. Compare the generated hash value to the previous returned hash value.

Step 5: Webhook notifications

We can also send Webhook Notifications to update your application with the transaction outcome. This allows you to update your systems whenever the status of a tds authenticated transaction reaches its final status, removing the need for the merchant to rely on the form POST to the redirect url.

Click here to view the webhook documentation including, the headers, parameters and webhook retry policy.

📘

Note

The final status of the transaction will be either: success declined tds_error tds_failed tds_expired

Step 6: Validate the integrity of the webhook

To validate the integrity of the webhook you generate a new hash value and compare it to the returned hash value. If the values match then the data has not been altered and the integrity of the data has been verified. To understand how to do so, navigate to our Webhook Notifications guide.

Error status responses

It is possible for errors to occur whilst the cardholder is authenticating themselves with their bank, for all possible statuses, see here. To view the 3DS reasons click here.

If you want to let the cardholder try the payment again, you should submit a new request to the payments endpoint.

Testing 3-D secure

For more information on how to test the 3DS process, view our 3DS testing guide here.

Liability shift

The 3-D Secure liability shift is a rule that protects the merchant from fraudulent transactions. When a payment is successfully authenticated with 3DS and the cardholder later disputes the transaction as fraud, the liability shifts from the merchant to the issuer.