3D Secure

Overview

3D Secure (3DS) is an authentication protocol that adds an extra layer of security for online card transactions, reducing the risk of unauthorized card usage and mitigating fraud by requiring additional authentication from the cardholder.

When a card authorization requires 3DS, Payrails returns the information needed to take the customer through the challenge as part of the authorization flow. This page covers:

• The two integration patterns for handling the 3DS redirect
• The threeDS response object you receive when authentication completes

If you're using the Payrails Drop-in or any of our SDKs, 3DS is handled for you and you can skip to the threeDS object reference.

Handling 3DS during authorization

When you authorize a card payment via API, the response always includes a links.consumerWait URL. You can use it in one of two ways.

Managed redirect with consumerWait

Redirect the customer to links.consumerWait after authorizing. Payrails handles the 3DS challenge if one is required, and returns the customer to your returnInfo.success URL when the session is complete. This is the integration pattern documented in our accept payments via API and authorize a payment guides.

The customer sees a Payrails-hosted intermediate page while the execution resolves, followed by either the 3DS challenge or your return URL.

Manual redirect with links.3ds

If you'd rather handle the 3DS redirect yourself (for example, to avoid showing a Payrails-hosted intermediate page on non-3DS payments), you can detect the 3DS step from the execution state and redirect to links.3ds directly.

1. After calling Authorize a payment, long-poll the execution:

   HTTP

   GET /merchant/workflows/{workflowCode}/executions/{executionId}?waitWhile[status]=authorizeRequested

2. When the request returns, check actionRequired on the execution:

   JSON

   {
     "id": "99e2f33a-2d17-4c98-8242-6bf5a4a08016",
     "actionRequired": "3ds",
     "links": {
       "3ds": "https://api.payrails.io/public/redirect/merchant/..."
     }
   }

   • If actionRequired is "3ds", redirect the customer to links.3ds.
   • If actionRequired is absent and the authorization has reached a terminal state, no challenge was required.

3. After the 3DS challenge completes, Payrails redirects the customer to your returnInfo.success URL. The final authorization result arrives via webhook notification.

📘

Note that this pattern handles 3DS only. If you use payment methods that require other types of redirects (such as APM hosted payment pages), the managed flow above handles those transparently while the manual flow does not.

The threeDS object

The threeDS object encapsulates various parameters related to the 3DS authentication process. It provides detailed information about the authentication status, transaction identifiers, and relevant parameters. You can expect to receive the threeDS object in the Notifications under paymentComposition. Below is a breakdown of the key components within the threeDS object:

"threeDS": {
  "authenticationValue": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
  "challenged": true,
  "dsTransId": "5ed5d1d0-982f-45f4-97a1-68651ac429d0",
  "eci": "05",
  "enrolled": "Y",
  "exemptionApplied": "none",
  "exemptionIndicator": "none",
  "transStatus": "Y",
  "version": "2.2.0"
}

📘

The structure of the object is based in the EMV 3DS 2.3.1.1 specification (PDF). However, depending on the availability of those fields in the response from your payment provider, we may not have all of them for all cases. Please contact our team to make sure you will get all the information you need for your processing.

Parameters

eci values

According to the 3DS specification, the following are the possible values for the eci field.

transStatus values

According to the 3DS specification, the following are the possible values for the transStatus field.