3D Secure
3D Secure (3DS) is the step where the buyer's bank checks that the person paying owns the card, before it approves the payment. On Flint, the hosted pages run that step for you, and every other integration gets the same thing back when the bank asks: one Flint URL to open, then a call to continue the same payment. There is no Stripe client secret in Flint's API responses to handle, the same action works on the web, in a native app, and from an AI agent's backend, and a repeated request never charges twice.
This guide assumes you take payments through an order or a payment intent. Flint processes cards through Stripe, so the challenge page the buyer sees is Stripe's and the bank's.
What 3D Secure and SCA are#
When a card payment starts, the processor sends the bank details about the payment and the buyer's device. The bank then does one of three things:
- Approves without a challenge. The bank is satisfied by the data alone. This is the frictionless flow of 3D Secure 2 (3DS2), and the buyer sees nothing.
- Challenges the buyer. The bank shows a step of its own, such as a one-time code or an approval in its banking app. The payment waits until the buyer finishes or gives up.
- Doesn't take part. Some cards don't support 3D Secure, and the bank's service can fail. The payment then continues without authentication.
3DS2 is the current version of the protocol, and the one Stripe runs for Flint payments. Major card brands no longer support 3D Secure 1.
Strong customer authentication (SCA) is the European rule, part of the EU's PSD2 regulation and adopted in the UK, that requires most online card payments to be authenticated, with 3D Secure as the method for cards. It binds businesses based in the European Economic Area that serve customers there. Flint onboards US businesses and charges in USD, so SCA doesn't apply to your account the way it does to a European seller. A bank can still ask for 3D Secure on any payment, and European banks in particular can challenge payments from your European buyers, so every integration that takes cards needs to handle the step.
When a bank asks for authentication#
Stripe starts 3D Secure when a regulation requires it, when the bank asks with a soft decline, or when one of Stripe's own checks applies. On Flint, a require_3ds risk rule can also ask for it. The bank always decides whether to challenge.
Payments made without the buyer present are never challenged, because nobody can answer. These are subscription renewals, automatic invoice charges, and order payments with customer_presence: "absent". Flint sends them to the card network as merchant-initiated charges on a saved card, backed by the authentication the buyer completed when the card was saved. If the bank still insists on authentication, the payment fails with authentication_required instead of waiting. When a payment without the buyer fails covers recovery.
Where the challenge runs#
| How you take the payment | Who runs the challenge | What you build |
|---|---|---|
| Hosted checkout, payment links, and the hosted invoice page | Flint's checkout page shows Stripe's challenge over the payment form. | Nothing. Fulfill from order.paid. |
| Embedded payments and your own checkout | Your page opens the Flint URL in the order payment attempt's pending_actions. | Open the URL and resume. |
| Server-confirmed payments | Your page opens the Flint URL in the payment intent's current_payment_action. | Open the URL and confirm again. |
| A card field in a native app | The app opens the Flint URL in a system browser view, which returns to your app. | Open the URL with a payment_return_url for the app. |
| Saving a card without a payment | Stripe.js confirmSetup runs it on your page. | Nothing beyond the save flow. |
| Saving a card while paying | Same as the payment. One authentication covers both. | Nothing extra. |
| A saved card with the customer present | Same as any order payment. The bank can still challenge. | Handle the action as for a new card. |
Renewals, automatic invoices, and customer_presence: "absent" | Nobody. These are never challenged. | Recover a payment that fails. |
A hosted checkout session can reach expires_at while the buyer is still on a challenge. The session stays usable for that payment alone, so the buyer can finish. Finish a payment after expiry has the rules.
Handle the next action#
When the bank asks for a challenge on an order payment, POST /v1/orders/{order_id}/pay returns 200 with the attempt in requires_action and one pending action for each payment that needs it. Open each action's URL, then resume the attempt. A failed challenge also returns 200, so read the attempt's status, not the HTTP status.
- Your backend sends POST /v1/orders/{order_id}/pay to Flint
- Flint returns requires_action with pending_actions[] to Your backend
- Your backend sends client_action.url to Browser
- Browser sends the buyer completes the bank's challenge to Browser
- Browser sends the buyer returned to Your backend
- Your backend sends pay with action: "resume" to Flint
- Flint returns succeeded, failed, or requires_action to Your backend
Continue a standalone payment intent#
A server-confirmed payment intent works the same way. The confirm response has status: "requires_action" and the action in current_payment_action. Open its URL, then confirm again without payment_source. The result is succeeded, requires_capture, or processing when the buyer authenticated, requires_action again when they haven't finished, and requires_payment_method with authentication_required when they failed. The step on a standalone payment intent expires 12 hours after the confirm call that returned the action.
The payment_intent.requires_action webhook doesn't carry the action. Confirm without payment_source to get it.
Recover the action after a lost response#
A replayed pay or confirm request returns the original result without the action URL. Read the attempt with GET /v1/orders/{order_id}/payment-attempts/{order_payment_attempt_id}, or confirm the payment intent again without payment_source, to get the current action. Recover a lost response covers the full recovery.
Use Stripe.js instead#
If your page already uses Stripe.js for authentication, send client_action_type: "stripe" on the request that starts the payment. The action then carries client_action.stripe with a publishable key, an optional account ID, and a client secret for stripe.handleNextAction. That secret can also confirm the payment with another card, so pass it only to handleNextAction. Embedded payments has the code.
- The type is fixed per payment. A continuation that leaves out
client_action_typekeeps the original type. A different explicit type returns409 ACTION_NOT_ALLOWEDwith reasonfield_locked. - Some steps can't open as a URL. Pay or confirm then returns
409 ACTION_NOT_ALLOWEDwith reasonprovider_action_unsupported. Continue withclient_action_type: "stripe". - Card readers use only
stripe. Sendingurlwith areadercredential returns400 INVALID_REQUEST.
Require 3D Secure with a risk rule#
A require_3ds risk rule asks for 3D Secure on the payments it matches. Use it for payments you consider risky, such as large orders or cards issued abroad. This rule asks for 3D Secure on card payments from cards issued outside the US, except virtual terminal payments:
curl -X POST https://api.withflintpay.com/v1/risk-rules \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: rule-3ds-foreign-cards-001" \
-d '{
"action": "require_3ds",
"description": "Require 3D Secure for cards issued outside the US",
"predicate": {
"all": [
{"attribute": "payment_method_type", "operator": "eq", "value": "card"},
{"attribute": "card_country", "operator": "neq", "value": "US"},
{"attribute": "payment_flow", "operator": "neq", "value": "virtual_terminal"}
]
}
}'
The rule comes back with stage: "pre_authorization" and applicability: "on_session_only", and applies from the next payment attempt. When it matches, Flint asks Stripe to run 3D Secure on the payment. The bank still decides: it can approve without a challenge, and a card that doesn't support 3D Secure goes through without it.
- It adds to other rules. Every matching
require_3dsrule adds the requirement, whatever your allow, block, and review rules decide. Anallowrule doesn't skip it. - It reads only what's known before authorization. A
require_3dsrule can't readrisk_levelorrisk_score, which come back after authorization. - Payments without the buyer skip it. Renewals, automatic invoice charges, and
customer_presence: "absent"payments ignorerequire_3ds. - Limit it to cards. A
require_3dsrule that matches an ACH debit fails the payment with409 PAYMENT_OPTION_UNAVAILABLE, reasonrisk_action_unsupported. Includepayment_method_typeeqcard. - Card readers can't run it. A card reader payment counts as
payment_method_typecard, and no attribute separates it from other card payments, so a matchingrequire_3dsrule, including the sample above for a foreign card, fails the reader payment with409 PAYMENT_OPTION_UNAVAILABLE, reasonrisk_action_unsupported. If you take reader payments, don't write arequire_3dsrule that could match them, such as one on every card payment. - Exclude the virtual terminal. The cardholder isn't there to authenticate a payment the seller keys in, so a matching rule fails it with
409 ACTION_NOT_ALLOWED, reasonconfiguration_required.
The payment intent's risk is null while the payment waits for 3D Secure, and fills in once Flint finishes checking it. Write a rule covers previews, attributes, and lists, and Test your rules shows how to scope a test rule to tagged payments.
When a challenge fails or is abandoned#
The buyer fails the challenge or closes it. Resume anyway. The attempt returns failed, with the payment intent back at requires_payment_method and last_payment_error.code authentication_required. Collect another card and start a new payment. If you start the new payment without resuming first, Flint refreshes the open attempt from Stripe before it judges the new one, so the buyer isn't blocked. Hosted checkout tells the buyer that their bank needs to verify the payment and lets them try again.
The buyer leaves without finishing. An order payment attempt stays requires_action until 30 minutes after it started. Flint then cancels its payments, the attempt ends canceled, and everything it held on the order is released, including reserved stock and promotion redemptions. The next payment starts fresh with action: "pay". To release the order sooner, cancel the attempt. A standalone payment intent's step expires 12 hours after the confirm call that returned the action.
Saving a card fails the check. confirmSetup returns the error in the browser, the card moves to failed, with failure_code authentication_required for a failed check, and payment_method.failed is sent. The same form accepts another try, and the same card moves to active when one succeeds.
When a payment without the buyer fails#
A renewal, an automatic invoice charge, or a customer_presence: "absent" payment that the bank won't approve without authentication fails with authentication_required. It never waits in requires_action.
- Subscription renewals.
authentication_requiredis a permanent decline: Flint stops automatic retries and sendssubscription.dunning_exhaustedwith the subscription stillpast_due. Have the customer save a new card, whose setup runs 3D Secure, point the subscription at it, and start a payment retry. Recover with a new card has the requests. - Automatic invoices. The customer can pay by card from the invoice's hosted page, where the bank's challenge runs with them present.
- Your own off-session charges. Don't charge the card again without the customer. Ask them to pay while present, for example through a checkout session for the order.
Liability shift#
When a cardholder disputes a payment as fraud, the merchant normally bears the loss. For a payment the bank authenticated with 3D Secure, the card networks generally move that fraud liability to the bank instead. Stripe describes this as an expectation, not a guarantee:
- It applies to eligible fraud disputes on payments that were successfully authenticated. A dispute for another reason, such as an item not received, follows the normal process.
- It doesn't generally apply when the card doesn't support 3D Secure or authentication errored and the payment went through without it.
- Network rules, the payment's conditions, and programs such as fraud monitoring can remove it for a specific payment.
- You can still receive an inquiry on an authenticated payment. Respond to it: an unanswered inquiry can become a chargeback that loses the liability shift.
Flint's API doesn't report a payment's 3D Secure result or electronic commerce indicator today, so don't treat a succeeded payment as proof that liability shifted. Respond to every dispute with evidence, as Handle disputes describes. Stripe's disputes and liability shift section is the source for these rules.
Rehearse 3D Secure in a sandbox#
Flint sandboxes use Stripe's test mode, so Stripe's 3DS test cards work in hosted checkout, in Stripe Elements on your page, and in the native SDKs. Use any future expiry date and any CVC. The sandbox challenge is a test dialog where you pass or fail authentication.
| Card | What it does |
|---|---|
| Challenges on a payment with the buyer present. Once saved, it charges without the buyer and no challenge. | |
Always challenges. Complete it and the payment succeeds; fail it and the attempt ends failed with authentication_required. | |
4000 0027 6000 3184 | Challenges on every payment, even after it's saved, so an automatic invoice or renewal with it fails because the bank requires authentication. |
4000 0084 0000 1629 | Challenges, then declines with card_declined after the buyer authenticates. |
4000 0000 0000 3055 | Supports 3D Secure but doesn't require it, so it pays with no challenge until a matching require_3ds rule asks Stripe to run 3D Secure. |
| Supports 3D Secure but isn't enrolled, so the buyer is never prompted, even when a rule asks. |
To pay from a terminal or a test suite, send a test payment method as payment_source.stripe.payment_method with credential_type: "stripe_payment_method":
| Payment method | What it does |
|---|---|
pm_card_authenticationRequired | The attempt stops at requires_action with a 3D Secure step for the browser. |
pm_card_threeDSecure2Required | The same, using 3DS2. |
The API alone can't complete a challenge, so open the returned URL in a browser to finish one, then resume. Test four outcomes before you go live: a challenge that passes, one that fails, one the buyer abandons, and a lost response replayed with the same Idempotency-Key.
The test card lookup lists every 3DS card by scenario, with the full Stripe test card list. If you're moving from another processor, the Adyen and Braintree pages list their 3DS cards and the same tests on Flint.
Webhooks#
The pay or confirm response already tells your backend what to do next. Webhooks carry the outcome to systems that weren't part of the request:
A card save that fails its check sends payment_method.failed, and a subscription payment retry that needs authentication sends subscription_payment_retry.failed with authentication_required. Webhooks covers signature checks and duplicate deliveries.
Errors#
These are the errors specific to 3D Secure. Error handling covers the envelope and the codes every route shares.
Known limits#
- Subscriptions created with the API can't run a challenge.
POST /v1/subscriptionsreturns no authentication step, and subscription payment retries carry no client action. Start a subscription through a hosted or headless checkout for its plan instead: the first charge is an order payment and handles 3D Secure as above. - Native apps use the URL action. With
client_action_type: "stripe", Flint doesn't confirm card-token payments for the Stripe mobile SDKs' in-app challenge, so a native app should open the Flint URL as Payments in mobile apps shows, not request thestripehandoff. - The browser holds Stripe's client secret during a hosted 3DS2 challenge. Flint's API never returns it for a URL action, but Stripe's hosted 3DS2 page receives it in its URL to run the challenge. If anyone uses it to confirm the payment with a card Flint didn't approve, Flint doesn't count that charge and returns it to the buyer, and the payment intent ends
canceledwithcancellation_reason: payment_returned. - No 3D Secure result on the payment. Flint doesn't expose the authentication outcome or electronic commerce indicator yet. See Liability shift.
Related guides#
- Declines and payment attempts: reading attempts, decline codes, and recovering lost responses.
- Embedded payments with Stripe Elements: the browser code for collecting a card and opening the action.
- Server-confirmed payments: standalone payment intents confirmed from your server.
- Save a card and charge it later: authentication when saving and charging later.
- Risk controls: every rule action, attribute, and list.
- Testing: every test card and token.