Secure Fields and 3DS

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

Approach	Best for	Implementation
Native 3DS	Custom UI, full control, embedded experience	You build the 3DS challenge UI using Secure Fields components
Hosted 3DS	Minimal setup, rapid deployment	Gr4vy provides a fully managed 3DS flow

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:

Value	Dimensions
`'01'`	250px × 400px
`'02'`	390px × 400px
`'03'`	500px × 600px
`'04'`	600px × 400px
`'05'`	Full container dimensions (default)

The examples use a <dialog> as the container for the 3-D Secure UI, but any container can be used.

import { useRef } from 'react';
import { ThreeDSecure } from '@gr4vy/secure-fields-react';

function ThreeDSecureWrapper() {
  const containerRef = useRef(null);
  return (
    <dialog ref={containerRef} open={false}>
      <ThreeDSecure
        ref={containerRef}
        // optional, if omitted it defaults internally to "05"
        challengeWindowSize="05"
      />
    </dialog>
  );
}

<dialog id="three-d-secure-container"></dialog>

<!-- approach 1 -->
<script>
  secureFields.addThreeDSecure(
    // you can pass a selector for the container
    '#three-d-secure-container',
    // and optionally, a configuration object, if omitted it defaults
    // internally to the value provided here
    { challengeWindowSize: '05' }
  );
</script>

<!-- approach 2 -->
<script>
  // alternatively, you can initialize 3-D Secure also
  // passing the container itself
  const container = document.getElementById('three-d-secure-container');
  // the configuration object (2nd parameter) is optional
  secureFields.addThreeDSecure(container);
</script>

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.

// element is the element specified by ref.
<ThreeDSecure
  onThreeDSStart={({ element }) => element?.showModal()}
  ref={containerRef}
/>

secureFields.addEventListener(
  SecureFields.Events.THREE_DS_START,
  // element is the element specified during initialization,
  // by addThreeDSecure().
  ({ element }) => element.showModal()
)

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.

<ThreeDSecure
  ref={containerRef}
  onThreeDSStart={({ element }) => element?.showModal()}
  onThreeDSFinish={({ element, tokenized, authentication }) => {
    // here you can perform operations based
    // on tokenized or authentication

    element?.close(); // you can also clear any UI container
  }}
/>

secureFields.addEventListener(
  SecureFields.Events.THREE_DS_FINISH,
  ({ element, tokenized, authentication }) => {
    // here you can perform operations based
    // on tokenized or authentication

    element.close(); // you can also clear any UI container
  }
)

These are the arguments received by the 3-D Secure finish callback:

Argument	Type	Description
`element`	`HTMLElement`	The HTML container (for example, dialog) used to display the 3-D Secure UI.
`tokenized`	`boolean`	Indicates whether the card data was successfully tokenized.
`authentication`	`Object`	The result of the 3-D Secure authentication.

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.

Property	Type or value	Description
`transaction_status`	`"Y"`	Authentication was successful.
	`"A"`	Not authenticated, but a proof of authentication attempt was generated.
	`"N"`	Not authenticated; the transaction was denied.
	`"R"`	Authentication was rejected by the issuer, which requests that authorization not be attempted.
	`"U"`	Authentication could not be performed because of a technical or other problem.
	`null`	No authentication status could be determined, typically only when an error occurred during authentication.
`type`	`null`	The flow failed because the card used is not enrolled
	`"challenge"`	The flow required the user to perform a challenge
	`"frictionless"`	The flow was successful without requiring a challenge
	`"error"`	The flow encountered an error during the process
`attempted`	`boolean`	Indicates if authentication was attempted
`timed_out`	`boolean`	Indicates if the authentication process timed out
`user_cancelled`	`boolean`	Indicates if the user cancelled the challenge

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.

import { useRef } from 'react';
import { ThreeDSecure, useSecureFields } from '@gr4vy/secure-fields-react';

function Checkout({ needs3DS }) {
  const { secureFields } = useSecureFields();
  const containerRef = useRef(null);

  const handleSubmit = () => {
    secureFields.setThreeDSecureEnabled(needs3DS);
    secureFields.submit();
  };

  return (
    <>
      {/* keep <ThreeDSecure> mounted and toggle 3-D Secure with setThreeDSecureEnabled() */}
      <dialog ref={containerRef} open={false}>
        <ThreeDSecure
          ref={containerRef}
          onThreeDSStart={({ element }) => element?.showModal()}
          onThreeDSFinish={({ element }) => element?.close()}
        />
      </dialog>
      <button type="button" onClick={handleSubmit}>Pay</button>
    </>
  );
}

secureFields.setThreeDSecureEnabled(needs3DS);
secureFields.submit();

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.

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 final EMV 3DS 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"

Based on these values, you can decide to proceed with the transaction creation or inform the user accordingly. The authentication result is included in the transaction response and can be used for reporting, compliance, or business logic decisions.

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

Card Number	Expected 3DS Outcome
`4000 0000 0000 0010`	Frictionless Success: Authenticated without user interaction.
`4000 0000 0000 0028`	Challenge Required: Triggers a 3DS challenge UI.
`4000 0000 0000 0044`	Authentication Failed: Simulates a “Not Authenticated” result.
`4000 0000 0000 1042`	Rejected: The authentication request was explicitly rejected.

Mastercard

Card Number	Expected 3DS Outcome
`5100 0000 0000 0010`	Challenge Required: Triggers a 3DS challenge UI.
`5200 0000 0000 2052`	Frictionless Success: Authenticated without user interaction.
`5200 0000 0000 1039`	Unavailable: Simulates a scenario where 3DS is not available for the card.
`5100 0000 0000 0065`	Suspected Fraud: Frictionless failure due to suspected fraud.

American Express

Card Number	Expected 3DS Outcome
`3415 0209 8634 895`	Frictionless Success: Authenticated without user interaction.
`3486 3826 7931 507`	Challenge Required: Triggers a 3DS challenge UI.
`3456 9539 9207 589`	Authentication Failed: Frictionless failure.

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:

OTP Code	Resulting Transaction Status	Description
`1234`	Y	Success / Authenticated.
`1111`	N	Not Authenticated.
`2222`	R	Rejected.
`3333`	U	Unavailable / Unable to complete.

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

Verify UI transitions: Ensure your app correctly transitions from the card entry screen to the 3DS challenge modal and back.
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.
Check authentication outcome: After a successful test, verify that the authentication object in your callback reflects the expected result before attempting the final transaction.

Get started

Integration guides

Best Practices

Resources

Features

Other

Secure Fields and 3DS

Overview

Choose your approach

Hosted 3DS Solution

Native 3DS implementation

Prerequisites

Merchant account-level configuration

How it works

Limitations & Considerations

Initialization

Showing the 3-D Secure UI

Receiving the 3-D Secure result

Running 3-D Secure for some cards only

Flow rules or your checkout?

Stored cards

After authentication

Testing and validation

Test cards

Visa

Mastercard

American Express

Challenge screen inputs

OTP (One-Time Password)

Selection options

Best practices for testing

​Overview

​Choose your approach

Hosted 3DS Solution

​Native 3DS implementation

​Prerequisites

Merchant account-level configuration

​How it works

​Limitations & Considerations

​Initialization

​Showing the 3-D Secure UI

​Receiving the 3-D Secure result

​Running 3-D Secure for some cards only

​Flow rules or your checkout?

​Stored cards

​After authentication

​Testing and validation

​Test cards

​Visa

​Mastercard

​American Express

​Challenge screen inputs

​OTP (One-Time Password)

​Selection options

​Best practices for testing

Overview

Choose your approach

Native 3DS implementation

Prerequisites

How it works

Limitations & Considerations

Initialization

Showing the 3-D Secure UI

Receiving the 3-D Secure result

Running 3-D Secure for some cards only

Flow rules or your checkout?

Stored cards

After authentication

Testing and validation

Test cards

Visa

Mastercard

American Express

Challenge screen inputs

OTP (One-Time Password)

Selection options

Best practices for testing