Incident

Dozens of DodoPayments subscription payments are stuck in status "Requires customer action" (3DS/SCA not completed). The same customers stack 4-5 duplicate attempts, and the overlay freezes on "Processing… / Payment Link Expires in 00:00." This is multi-factor: a mix of Dodo-overlay reality our integration got wrong and our own return/webhook handling being blind to the state.

How a 3DS payment dies (mechanism)

1. Card needs 3DS. Dodo's overlay runs the challenge via Hyperswitch inside the iframe; banks that block iframe rendering force a full-page redirect to the bank (the overlay iframe sandbox has no allow-top-navigation, so redirects bubble out via postMessage).
2. After the bank, Dodo returns the user to return_url = bare origin → the welcome marketing page (regression feat: serve welcome at root and dashboard at /dashboard #4307), which never reconciles the return → the user gets no success/failure signal.
3. So the user retries → a brand-new payment (no idempotency key; dedup guard can't see pre-webhook attempts) → the stacked duplicates on the dashboard.
4. Our webhook drops requires_customer_action/processing (records them as status:"processed" but persists no pending state) → we're blind: no pending-payment signal, so no duplicate-prevention, no reconciliation, no resume path → they rot at "requires_customer_action" forever. (Dedup is by webhookId, so later distinct transitions still arrive — the harm is the lost pending signal, not blocked transitions.)

What is NOT the cause (don't chase)

The backend checkout payload is correct: on-session (no confirm/payment_method_id, so Dodo does present the 3DS UI), correct product_cart/metadata, and there is no expiry param to set on checkoutSessions.create. The "00:00" timer is Dodo's showTimer on the session's server-side expires_at (24h default, since we don't set confirm=true) — a symptom, not the root cause.

Child issues

P0 — stops the bleeding:

• fix(checkout): P0 — overlay iframe hangs Dodo 3DS/fraud stack at 'Processing' (move to redirect mode) #4449 — PRIMARY ROOT CAUSE (HAR-confirmed): the overlay iframe hangs Dodo's nested 3DS/fraud stack (Hyperswitch→Airwallex→Sardine) at "Processing…". confirm returns 200 then no terminal status ever arrives — upstream of the redirect/return/webhook factors below. Fix = displayType:'redirect'.
• fix(checkout): P0 — post-3DS return_url lands on welcome page, never reconciled (regression from #4307) #4434 — return_url lands on welcome page, never reconciled (regression feat: serve welcome at root and dashboard at /dashboard #4307)
• fix(checkout): P0 — no checkout.link_expired handler → overlay frozen at 'Processing 00:00' #4435 — no checkout.link_expired handler → frozen "Processing 00:00" overlay
• fix(payments): P0 — webhook drops requires_customer_action/processing → loses pending-payment signal #4436 — webhook drops requires_customer_action/processing → loses pending-payment signal

P1 — correctness + duplicates:

• fix(checkout): P1 — redirect_requested treated as success before 3DS authentication #4437 — redirect_requested treated as success before 3DS authentication
• fix(payments): P1 — duplicate stuck payments (no idempotency key + dedup blind to pending 3DS) #4438 — duplicate stuck payments (no idempotency key + dedup blind to pending)
• fix(checkout): P1 — entitlement watchdog gives up silently on requires_customer_action timeout #4439 — watchdog gives up silently on requires_customer_action timeout

P2 — follow-ups (flagged, not yet split out):

• Daily reconciliation cron: poll Dodo for payments stuck in requires_customer_action past a threshold → email a fresh checkout link / cancel. (convex/crons.ts has no payment reconciliation today.)
• Strategic: evaluate displayType:'redirect' → promoted to P0 fix(checkout): P0 — overlay iframe hangs Dodo 3DS/fraud stack at 'Processing' (move to redirect mode) #4449 (HAR confirmed it's the primary user-facing hang, not a "later" item).

How this was diagnosed

Four adversarial agents (backend checkout-creation params, frontend overlay/3DS, webhook status handling, Dodo docs research) + direct reads of SDK 1.8.0 (dodopayments-checkout/dist/index.esm.js) and an independent Codex review converged on the same multi-factor picture above.