3D Secure (3DS) is a security protocol that adds a layer of verification to card-not-present (CNP) transactions by verifying the cardholder's identity through the issuing bank. This technical standard mitigates fraud and chargebacks while fostering trust in ecommerce environments.

3D Secure 2 guide

3D Secure 2 (3DS2) is the second iteration of the 3DS protocol designed to meet Strong Customer Authentication (SCA) requirements from the PSD2 in Europe and similar regulations in the UK, India, Japan, and Australia. 3DS2 improves the customer's purchase experience compared to 3D Secure 1 (now deprecated).

3DS2 introduces frictionless authentication, which uses data points to validate the cardholder's identity without requiring the customer to take any action.

Liability shift

3DS can shift liability from the supplier to the issuing bank for specific 3DS-related chargebacks. An Electronic Commerce Indicator (ECI) is the response to a 3DS authentication attempt and indicates the liable party in the event of a transaction dispute.

Reach provides the ECI value sent by the payment processor in our /query endpoint API response. To view the ECI value, call the /query endpoint with the OrderId . The Eci field can be found under the ThreeDS object in the response body. See ECI values for a reference list and further details.

{
  ...,
  "ThreeDS": {
    "Eci": "05",
    "MessageVersion": "2.2.0"
  }
}

Basic 3DS flow

The shopper selects a credit card as the payment method and completes payment. In a 3DS frictionless flow the shopper experience appears the same, with 3DS being run behind the scenes. In a challenge flow, Reach returns a URL to the supplier, redirecting the shopper to a 3DS authentication page.

The shopper completes the 3DS flow by either validating their bank login or entering a One-Time Code (OTC). Reach receives shipping and billing details, as well as confirmation of 3DS authentication status.

The shopper is redirected to the supplier's return URL. An authorization notification will be sent, and may arrive before or after the return URL is fetched.

3DS2 and the Checkout API

If additional action must be taken to proceed with a /checkout or /openContract request, the Action object contains information about the required action inlcuding information about 3DS.

{
    "MerchantId": "e78e8cd0-24b8-4b0c-a922-87a1d8cc61c3",
    "ReferenceId": "1553817109050",
    "PaymentMethod": "VISA",
    "ConsumerCurrency": "EUR",
    "Capture": true,
    "Items": [{
        "Description": "Frying Pan",
        "ConsumerPrice": 100,
        "Quantity": 1,
        "Sku": "4383471583721"
    }],
    "Consumer": {
        "Name": "John Doe",
        "Email": "[email protected]",
        "Address": "123 Any Street",
        "City": "Somewhere",
        "Country": "DE"
    },
    "DeviceFingerprint": "a598d668-f75d-4046-8e2f-ca0f6825ede0",
    "Return": "https://checkout-sandbox.gointerpay.net/return.php"
}

{
  "OrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "UnderReview": true,
  "Expiry": "2026-03-24T17:17:50.460Z",
  "ContractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Authorized": true,
  "Captured": true,
  "Action": {
    "Redirect": "string",
    "Challenge": "string",
    "Display": {}
  },
  }
}

  "Action": {
    "Redirect": "string",
    "Challenge": "string",
    "Display": {}
  },

Challenge flow

AChallenge response indicates that the transaction requires 3DS. The Challenge field will contain a URL to the 3DS authentication page.

Use this URL to embed a 3DS2 cardholder challenge within an iframe. The cardholder will interact with their bank's interface displayed in the iframe.

{
    "OrderId": "37b4194d-45a5-43d6-8cd1-ce7b1ef19f52",
    "UnderReview": false,
    "Expiry": "2019-04-07T23:52:47Z",
    "Authorized": false,
    "Completed": false,
    "Captured": false,
    "Action": {
        "Challenge": "https://sandbox.withreach.com/challenge/da68a9c2-1e26-4054-8543-27666faedfdd",
        "Redirect": "https://sandbox.withreach.com/renderChallenge/da68a9c2-1e26-4054-8543-27666faedfdd"
    }
}

The challenge() method—provided by the Reach Checkout API SDK—helps facilitate the display and management of the challenge. For full details, see the reach-sdk-checkout-web.

	document.getElementById("challenge").onclick = function(e) {
		window.rch.challenge(document.getElementById("https://sandbox.withreach.com/challenge/da68a9c2-1e26-4054-8543-27666faedfdd").value,
							document.getElementById("windowSize").value,
							document.getElementById("container"),
							callback, 
							loadedCallback					
		);

The callback function provides the challenge outcome and allows the developer to programmatically authorize or reject the transaction based on the result. The challenge() callback includes the ContractId if an authorization was opened with a contract.

Frictionless flow

SCA is not always required in the case where 3DS is required. For example, the issuing bank may deem the transaction low risk and use the provided data to authenticate the transaction without a cardholder challenge. This flow is called the "frictionless" flow.

In these instances, the challenge() method will call back with a result without displaying any iframe content.

Passing additional fields with the /checkoutrequest may increase the chances of a frictionless authentication, see the Optional fields section below.

Challenge redirect option

When a response contains a Challenge action, it includes a Redirect action. Redirecting the browser to the specified URL will display the iframe within a Reach-hosted web page. While this offers a straightforward interim solution, integrating directly with the Challenge action is recommended for optimal user experience.

Contract payments flow

The PaymentModelfield specifies whether the transaction is a merchant-initiated transaction (MIT) or consumer-initiated transaction (CIT) and how stored payment details will be used. Stored payment details may be managed via /openContract, a PCI DSS-compliant card vault, or you may create and store tokens through the /checkout request by setting theOpenContract field to true.

If the /checkout request is a MIT, then it is not subject to SCA and 3DS authentication challenges. Identify the relevant transactions as a MIT in the PaymentModel field.

CIT orders using a ContractId are subject to 3DS and SCA, so the response may still return an Action of Redirect or Challenge.

Testing 3DS2

Step 1. Update your code by sending API requests to support 3DS2

1. Include a return URL in /checkout and /openContract requests for card payments.

2. Be prepared to handle various Action responses returned for card transactions.
3. Use the Reach Checkout Web SDK on the frontend to display any required challenges and manage the user experience during the authentication process (including redirects).

Step 2. Test the 3DS2 flows

Testing the challenge flow

Use the following test cards to trigger a challenge flow. In the cardholder challenge window, provide password: in the password field for a successful authentication.

Testing the frictionless flow

To trigger the frictionless flow, use EUR 120.02 as the total consumer amount in the /checkout request.

Use the test card below to trigger a frictionless flow. In the cardholder challenge window, provide password: in the password field for a successful authentication.

Example of cardholder challenge

See the image below for an example of a cardholder challenge in a sandbox environment. This is the screen where the cardholder is prompted to enter their password to proceed with the transaction.

On completion, the iframe is removed, and the supplied callback function is called with an indication of authorization success or failure.

{ "authorized": true }

Optional fields

The following optional fields increase the likelihood of a frictionless flow when included with the /checkoutAPI request. The issuing bank will decide whether to use these fields when evaluating a transaction.

You can find further detailed field descriptions in the Checkout API reference page.

To provide more order information, include the following fields in the /checkout request:

In the Items object include the following fields:

• PreorderDate​
• ​Reorder​
• GiftCard​​

In the Shipping object include the following fields:

• ​Timeframe​

In the ConsumerProfile object (within the Consumer object) include the following fields:

• ConsumerProfileId (formerly Consumer.MerchantProfileId)
• OpenDate
• LastChange
• LastPasswordChange
• Purchases6Months
• AddCardAttempts24Hours
• Transactions24Hours
• Transactions1Year
• HadSuspiciousActivity

In the Consignee object include the following fields:

• ​AddedDate​
• VerifiedAddress​

Additional information

• Maestro is a debit card issued on the Mastercard network. It requires 3D Secure authentication for all non-recurring transactions. Implementing 3DS2 for PSD2 will enable the Maestro 3DS2 flow.

• Local India credit card processing requires 3D Secure authentication.
• The payment method requires a fingerprint.