Skip to main content

Overview

Secure Fields supports two distinct 3-D Secure approaches: a Native implementation you build and control, and a Hosted solution managed by Gr4vy. Both support Dynamic 3-D Secure configuration via Flow rules.

Choose your approach

Hosted 3DS Solution

Learn how to use the hosted 3DS solution with Secure Fields.

Native 3DS implementation

Prerequisites

Native 3DS requires merchant account-level 3-D Secure configuration to be set up. This is different from the per-connection setup and must be configured before using the native implementation.

Merchant account-level configuration

Follow the setup guide to configure 3DS at the merchant account level.

How it works

Native 3DS automatically handles all device fingerprinting requirements, including collecting the device’s IP address, user agent, and other authentication metadata needed for 3-D Secure compliance. You don’t need to manually collect or pass this data—the implementation handles it transparently.

Limitations & Considerations

When you use native 3DS with Secure Fields, it is important to pass the transaction context (for example, metadata, merchant_initiated, or cart_items) when you create the Checkout Session. Native 3DS runs before the transaction is created, so this context must already be present when you create the session. Gr4vy uses the session’s metadata to pick the 3DS configuration, and the full context to evaluate Flow rules. Additionally, it’s important to note that the system runs 3DS Flow rules at the time of the enrollment check, which is run at the time of submitting Secure Fields. Currently, this Flow rule check doesn’t support anti-fraud checks as these are currently tied to a transactions, though there are plans to add this in the near future.

Initialization

There are two ways to initialize the native 3-D Secure component: as a React component or through the vanilla JavaScript API (in Node or CDN scenarios). The property challengeWindowSize controls the size of the challenge window and can be set to the following values:
The examples use a <dialog> as the container for the 3-D Secure UI, but any container can be used.

Showing the 3-D Secure UI

With the 3-D Secure start callback, the 3-D Secure process start can be detected, allowing the container UI to be displayed. The start event fires for every 3-D Secure attempt, before Gr4vy knows whether the card needs a challenge. It also fires for frictionless authentications, for cards that aren’t enrolled, and when a Flow rule skips 3-D Secure. While the attempt runs, the 3-D Secure frame shows a loading indicator. Design your container for this short processing state instead of hiding it until a challenge appears.

Receiving the 3-D Secure result

With the 3-D Secure finish callback, the 3-D Secure process finish can be detected, allowing any UI element that was shown during the process to be dismissed and the outcome of the process to be received.
These are the arguments received by the 3-D Secure finish callback: The authentication object contains the following properties. The transaction_status values follow the EMV 3DS specification and are shared across every integration path — see Authentication results for the full reference. After a challenge, Secure Fields only receives some of them, as described in What Secure Fields receives.

What Secure Fields receives

The transaction_status in the finish callback comes from a different 3-D Secure message depending on the flow. The EMV 3DS specification only allows "Y" or "N" in a challenge response. The issuer sends its final challenge result in a separate results request (RReq), server to server, and that result can also be "R" or "U". Secure Fields never receives the results request. A challenge that the issuer rejects or can’t complete reaches your callback as "N". Gr4vy stores the final challenge result on the checkout session, but doesn’t return it in Secure Fields events or the checkout session API. It only reaches the transaction when authentication produced an authentication value, as described in After authentication. Vault Forward exposes it to forwarded requests as CARD_3DS_AUTHENTICATION_RESPONSE_1. The issuer’s reason code (transStatusReason) isn’t available through any of these.
The finish callback runs in the buyer’s browser, so treat transaction_status as a signal for your checkout UI, not as proof of authentication. A buyer can change values in their own browser before your code reads them. Base decisions that must hold up server-side on data your backend gets from Gr4vy, such as the three_d_secure result on the transaction.

Running 3-D Secure for some cards only

Once the 3-D Secure component is added, every submit() runs 3-D Secure. To run it only for some cards (for example, based on the BIN country), keep the component in place and call setThreeDSecureEnabled() before each submit(). In React, removing <ThreeDSecure> from the page also turns 3-D Secure off, and rendering it again turns it back on. Keeping the component mounted and calling setThreeDSecureEnabled() is the recommended approach, because each new render of the component loads the 3-D Secure frame again and submit() waits for it to load.
When 3-D Secure is disabled, submit() only vaults the card. CARD_VAULT_SUCCESS fires, and THREE_DS_START and THREE_DS_FINISH do not.
This requires @gr4vy/secure-fields and @gr4vy/secure-fields-react 2.11.1 or later. Earlier versions decide whether to run 3-D Secure once, when the component loads, and ignore later changes.

Flow rules or your checkout?

Flow rules for 3-D Secure are the simplest way to decide which transactions to authenticate, and Gr4vy evaluates them when Secure Fields submits. Decide in your checkout with setThreeDSecureEnabled() instead when:
  • The decision depends on data from your own systems that Flow rules can’t see.
  • You want the same logic on web and mobile, for example based on the issuing country from the card-details-changed event.
  • You don’t want the buyer to see the 3-D Secure container when no authentication runs. When a Flow rule skips 3-D Secure, the start event has already fired, so the buyer may see the container for a moment.

Co-badged cards

A co-badged card carries more than one network, for example Visa and Cartes Bancaires. 3-D Secure results are only valid for the network they were created on. If the buyer chose a network, call setPreferredScheme() with that network before you call submit(), so 3-D Secure runs on it.
Use the scheme IDs from the card-details-changed event, such as visa or carte-bancaire. Pass null to clear the choice. If the network isn’t on the card, 3-D Secure runs on the card’s primary network. Gr4vy records the network 3-D Secure ran on in the checkout session. A transaction created with that checkout session is processed on that network, even if the transaction sends a different preferred_scheme. See Customer-preferred scheme routing.

Stored cards

You can also run 3-D Secure on a card that the buyer stored earlier. See 3-D Secure with a stored card.

After authentication

Once you receive the 3-D Secure authentication result, you can determine whether authentication was attempted and whether it was successful. You can then proceed to create a transaction regardless of the outcome. The authentication object provides the following key signals:
  • attempted: Whether the authentication process was initiated
  • timed_out: Whether the authentication timed out before completing
  • user_cancelled: Whether the user dismissed the challenge
  • transaction_status: The 3-D Secure status visible in the browser. After a challenge, this isn’t always the issuer’s final result. One of "Y" (success), "A" (attempt generated), "N" (not authenticated), "R" (rejected by the issuer), "U" (could not be performed), or null (no status could be determined, typically only when an error occurred). A successful frictionless authentication returns "Y". After a challenge, only "Y" or "N" is possible, even when the issuer’s final result is "R" or "U". See What Secure Fields receives.
Based on these values, you can decide to proceed with the transaction creation or inform the user accordingly. When the checkout session passes 3-D Secure data to the transaction, as described below, the authentication result is included in the transaction response and can be used for reporting, compliance, or business logic decisions. Gr4vy doesn’t stop a transaction because of the authentication result. The checkout session only passes 3-D Secure data to the transaction when authentication produced an authentication value, for example with a transaction_status of "Y". After an "N" or "R", the transaction is created without 3-D Secure data. Your 3-D Secure settings and Flow rules then decide whether Gr4vy runs 3-D Secure again for that transaction. To avoid authorizing a payment that failed authentication, check transaction_status for the results you accept, for example "Y", and don’t create the transaction otherwise. Don’t build this rule around "R" alone, because after a challenge a rejection reaches the browser as "N". To keep this decision in Flow instead, pass the result as transaction metadata and add a Decline rule with a Metadata condition on that value. Both approaches rely on the value your checkout read in the browser. See the warning in What Secure Fields receives. 3-D Secure doesn’t capture the payment. The transaction’s intent controls capture, so with an intent of authorize you still need to capture the transaction after authorization. See Authentication and capture.

Testing and validation

To test your Native 3DS implementation, use the 3DS Test Cards in your sandbox environment. These cards allow you to simulate various outcomes, including frictionless authentication, mandatory challenges, and specific failure states.

Test cards

Visa

Mastercard

The challenge card 5100 0000 0000 0010 doesn’t pass a Luhn check. Secure Fields reports it as not valid, so a form that only submits valid card numbers blocks it. Allow this number in your sandbox form validation when you test the Mastercard challenge flow.

American Express

Challenge screen inputs

When a challenge is triggered, use the following values to simulate different transaction results.

OTP (One-Time Password)

When the challenge screen asks for a code, enter one of the following: The challenge response can only carry "Y" or "N", so the rejected and unavailable codes reach your callback as "N". See What Secure Fields receives.

Selection options

Some challenges may present a list of options (for example, “Select your favorite city”). Single-select
  • Paris or Nice: Returns Success (Y).
Multi-select
  • Paris & Lyon: Returns Success (Y).
  • Toulouse & Lyon: Returns Success (Y).

Best practices for testing

  1. Verify UI transitions: Ensure your app correctly transitions from the card entry screen to the 3DS challenge modal and back.
  2. Test error states: Use the “Rejected” or “Failed” cards to ensure your app displays helpful messaging to the user when a card cannot be verified.
  3. Check authentication outcome: After a successful test, verify that the authentication object in your callback reflects the expected result before attempting the final transaction.