EMV® 3-D Secure

EMV 3DS provides an additional layer of authentication for online businesses to ensure a purchase is from a legitimate cardholder. It helps to protect businesses from fraudulent chargebacks and comply with regulation 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.

status=success&transaction_id={{transaction_id}}&order_id={{order_id}}&timestamp={{timestamp}}&hash={{hash}}

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

Step 4: Webhook notifications

We can also send Webhook Notifications to update your application with the transaction status. 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 5: 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.

Follow the below steps to calculate the hash value:

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 the resulting string.

6a8310c7510493b87c0dc0fec7c4df4091eb021c040ee8b3dbf134f1c1ec6731

5. Compare the generated hash value, to the previously returned hash value.

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.

Example of a tds_failed response:

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

Example of a tds_error response:

{
  "transaction_id": "a7e3fde5-5b83-44f4-9915-876rf4326789",
  "status": "tds_error",
  "reason": "bad_gateway",
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-876rf4326789"
    }
  ]
}

Example of a tds_expired response:

{
  "transaction_id": "a7e3fde5-5n83-55f4-9915-895hn875676",
  "status": "tds_expired",
  "reason": "challenge_time_out",
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5n83-55f4-9915-895hn875676"
    }
  ]
}

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