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 enabled 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. As native 3DS runs before transaction creation, so this context must already be present at session creation time to find the right 3DS profile, as well as take into consideration any 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.

// 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:

Property	Type	Description
`transaction_status`	`"Y"`	The transaction was successful
	`"N"`	The transaction failed.
	`null`	The transaction status is unknown
`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

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 result ("Y" = success, "N" = failed, null = unknown)

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

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

​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

After authentication

Testing and validation

Test cards

Visa

Mastercard

American Express

Challenge screen inputs

OTP (One-Time Password)

Selection options

Best practices for testing