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 propertychallengeWindowSize 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 the3-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 the3-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.
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
Thetransaction_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.
Running 3-D Secure for some cards only
Once the 3-D Secure component is added, everysubmit() 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.
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 withsetThreeDSecureEnabled() 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-changedevent. - 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, callsetPreferredScheme() with that network before you call submit(), so 3-D Secure runs on it.
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. Theauthentication object provides the following key signals:
attempted: Whether the authentication process was initiatedtimed_out: Whether the authentication timed out before completinguser_cancelled: Whether the user dismissed the challengetransaction_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), ornull(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.
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).
- 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
authenticationobject in your callback reflects the expected result before attempting the final transaction.