Skip to content

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 paymentWho runs the challengeWhat you build
Hosted checkout, payment links, and the hosted invoice pageFlint's checkout page shows Stripe's challenge over the payment form.Nothing. Fulfill from order.paid.
Embedded payments and your own checkoutYour page opens the Flint URL in the order payment attempt's pending_actions.Open the URL and resume.
Server-confirmed paymentsYour 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 appThe 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 paymentStripe.js confirmSetup runs it on your page.Nothing beyond the save flow.
Saving a card while payingSame as the payment. One authentication covers both.Nothing extra.
A saved card with the customer presentSame 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.

An order payment with 3D SecureResponse
BrowserYour backendFlintPOST /v1/orders/{order_id}/payrequires_action with pending_actions[]client_action.urlthe buyer completes the bank's challengethe buyer returnedpay with action: "resume"succeeded, failed, or requires_action
  1. Your backend sends POST /v1/orders/{order_id}/pay to Flint
  2. Flint returns requires_action with pending_actions[] to Your backend
  3. Your backend sends client_action.url to Browser
  4. Browser sends the buyer completes the bank's challenge to Browser
  5. Browser sends the buyer returned to Your backend
  6. Your backend sends pay with action: "resume" to Flint
  7. Flint returns succeeded, failed, or requires_action to Your backend
  1. Pay the order#

    Pay as usual. This sandbox request uses Stripe's test payment method that always asks for 3DS2:

    <!-- docs-test {"scenario":"challenge","status":200,"response":false,"fixtures":{"order":9900},"expect":{"data.order_payment_attempt.status":"requires_action","data.order_payment_attempt.is_resumable":true}} -->

    cURL
    curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Idempotency-Key: pay-ord_1kmn0aExample-1" \
      -d '{
      "action": "pay",
      "payment_source": {
        "credential_type": "stripe_payment_method",
        "stripe": {
          "payment_method": "pm_card_threeDSecure2Required"
        }
      },
      "expected_outstanding_money": {
        "amount": 9900,
        "currency": "USD"
      },
      "payment_return_url": "https://shop.example/checkout/return"
    }'
    

    The attempt in the response carries the action:

    Response
    {
      "order_payment_attempt": {
        "order_payment_attempt_id": "opat_1kmn0aExample",
        "status": "requires_action",
        "is_resumable": true,
        "pending_actions": [{
          "pending_action_id": "pendact_1kmn0aExample",
          "subject": {"payment_intent": {"payment_intent_id": "pi_1kmn0aExample"}},
          "action_type": "payment_authentication",
          "expires_at": "2026-11-21T12:30:00Z",
          "client_action": {
            "type": "url",
            "url": "https://payment-returns.example/payment-returns/actions/pendact_1kmn0aExample/bearer-token"
          }
        }]
      }
    }
    

    client_action.type is url unless you asked for the Stripe.js handoff. pending_action_id stays the same across reads, so you can use it to avoid opening one action twice. expires_at is the attempt's cancel time, 30 minutes after it started.

    payment_return_url is optional with an API key. With a checkout credential, set it when you create the headless session and leave it out of pay and resume.

  2. Open the URL#

    Open each pending action's client_action.url before expires_at, in one of three ways:

    • A redirect. The simplest choice, and the best on small screens.
    • A popup. Open it directly from the buyer's click, and offer a redirect if the browser blocks it.
    • An iframe. Reserve at least 250 by 400 pixels, the smallest standard challenge size, and allow Stripe's frames in your content security policy.

    In a native app, open it in ASWebAuthenticationSession, Custom Tabs, or Expo's auth session, with your app's scheme or universal link as payment_return_url. Payments in mobile apps has the full flow.

    The URL is a bearer credential. Give it only to the buyer completing this step, and keep it out of logs and analytics.

    When the buyer finishes, Flint sends them to payment_return_url with one added parameter: payment_intent_id for a payment, or payment_method_id for a card setup. Without a return URL, the completion page posts a message to its parent and opener instead:

    JSON
    {"type": "flint.payment_action.completed", "payment_intent_id": "pi_1kmn0aExample"}
    

    Check event.origin against the origin of the action URL and event.source against the window you opened before you act on it. A return or a message only means the buyer left the step. They may have passed, failed, or closed it.

  3. Resume the attempt#

    Ask your backend to resume, with a new idempotency key:

    <!-- docs-test {"skip":"Requires a completed browser 3DS challenge before continuation; API-only test does not complete authentication."} -->

    cURL
    curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Idempotency-Key: pay-ord_1kmn0aExample-resume-1" \
      -d '{"action": "resume", "order_payment_attempt_id": "opat_1kmn0aExample"}'
    

    Flint reads the challenge result from Stripe and returns the attempt's next status:

    • succeeded: the order is paid. Fulfill from order.paid, as always.
    • failed: the buyer failed the challenge, and the payment intent's last_payment_error.code is authentication_required. Ask for another card, as in Retry after a decline.
    • requires_action: the buyer hasn't finished. Let them open the returned URL again.
    • processing: the payment is settling. Wait for order.paid, and don't pay again.

    You can also continue through the leg's payment intent: POST /v1/payment-intents/{payment_intent_id}/confirm with an empty body. It continues the same attempt and never starts another. Finish 3D Secure has the resume body's rules.

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_type keeps the original type. A different explicit type returns 409 ACTION_NOT_ALLOWED with reason field_locked.
  • Some steps can't open as a URL. Pay or confirm then returns 409 ACTION_NOT_ALLOWED with reason provider_action_unsupported. Continue with client_action_type: "stripe".
  • Card readers use only stripe. Sending url with a reader credential returns 400 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
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_3ds rule adds the requirement, whatever your allow, block, and review rules decide. An allow rule doesn't skip it.
  • It reads only what's known before authorization. A require_3ds rule can't read risk_level or risk_score, which come back after authorization.
  • Payments without the buyer skip it. Renewals, automatic invoice charges, and customer_presence: "absent" payments ignore require_3ds.
  • Limit it to cards. A require_3ds rule that matches an ACH debit fails the payment with 409 PAYMENT_OPTION_UNAVAILABLE, reason risk_action_unsupported. Include payment_method_type eq card.
  • Card readers can't run it. A card reader payment counts as payment_method_type card, and no attribute separates it from other card payments, so a matching require_3ds rule, including the sample above for a foreign card, fails the reader payment with 409 PAYMENT_OPTION_UNAVAILABLE, reason risk_action_unsupported. If you take reader payments, don't write a require_3ds rule 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, reason configuration_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_required is a permanent decline: Flint stops automatic retries and sends subscription.dunning_exhausted with the subscription still past_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.

CardWhat 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 3184Challenges 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 1629Challenges, then declines with card_declined after the buyer authenticates.
4000 0000 0000 3055Supports 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 methodWhat it does
pm_card_authenticationRequiredThe attempt stops at requires_action with a 3D Secure step for the browser.
pm_card_threeDSecure2RequiredThe 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:

  1. What happens: The bank asks for a challenge
  2. Flint sends: payment_intent.requires_action
    The payload doesn't carry the action. Read the attempt, or confirm without payment_source, to get it.
  3. What happens: The buyer passes
  4. Flint sends: payment_intent.succeeded
    One per payment that settled.
  5. Flint sends: order.paid
    Once, when the order is fully paid. Fulfill from this event.
  6. What happens: The buyer fails
  7. Flint sends: payment_intent.payment_failed
    last_payment_error.code is authentication_required.
  8. What happens: The buyer abandons the challenge
  9. Flint sends: payment_intent.canceled
    Sent when Flint cancels the attempt's payments at its cancel time.

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.

  • HTTP 409
    Read details[0].reason. field_locked: a continuation asked for a different client_action_type than the payment started with; leave the field out. provider_action_unsupported: the step can't open as a URL; continue with client_action_type: "stripe". configuration_required: a require_3ds rule matched a virtual terminal payment; exclude virtual_terminal from the rule. unsupported_state: the attempt you tried to resume is past its 30 minutes or waiting for capture; do what its status allows.
  • HTTP 409
    Reason risk_action_unsupported: a require_3ds rule matched an ACH debit. Limit the rule to cards with payment_method_type.
  • HTTP 400
    Detail code UNKNOWN_FIELD: a resume body included a field it doesn't accept, such as payment_source. Detail code INVALID_VALUE with param client_action_type: url was sent with a reader credential.
  • HTTP 409
    A resume reused the key of the request that started the payment. See Replay, conflict, or in progress.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    expected_outstanding_money on a resume doesn't match the amount fixed on the attempt. Read the order and show the buyer the current amount.

Known limits#

  • Subscriptions created with the API can't run a challenge. POST /v1/subscriptions returns 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 the stripe handoff.
  • 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 canceled with cancellation_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.

Was this helpful?