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.
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.
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.
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.
Copy
Ask AI
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> );}
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.
Copy
Ask AI
<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 }}/>
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
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.
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.
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.
