docs(sca): document Strong Customer Authentication for EU customers

[jklein24]

Summary

A full, EU-scoped Strong Customer Authentication guide in the Mintlify docs, covering the SCA surface added in #558/#600 (both merged). What began as a single per-transaction snippet is now a dedicated guide section covering the whole SCA surface the API exposes, mirroring the structure of the reference docs it wraps (Striga's SCA docs).

What's added

A new "Strong Customer Authentication" group under the Get started tab (docs.json), with six pages under platform-overview/sca/:

• overview — region scoping (EU / EUR / USDC), a "what SCA covers" table, factors + dynamic linking, a Mermaid flow diagram of the authorize loop, and lifetimes/limits + error tables.
• per-transaction-authorization — reuses the existing snippets/sca/strong-customer-authentication.mdx as the single source (the three money-movement flow pages still import the same snippet, so they're unchanged): PENDING_AUTHORIZATION + scaChallenge, the status-driven authorize loop, inline vs. after-the-fact proof, resend, realtime-funding quotes, sandbox 123456.
• factor-enrollment — TOTP + passkey enrollment (start/confirm), factor list/delete.
• login-and-sessions — SCA login + the session it grants, plus account-security (record-event) signals and the lockout ladder.
• trusted-beneficiaries — trust and untrust as start → confirm (keyed by externalAccountId).
• two-factor-reset — liveness-gated start → poll → complete.

Refreshed for API drift (2026-08-28)

Rebased onto current main — the branch previously carried #600's spec commits, which are merged, so the PR is now docs-only — and updated for everything that landed on the SCA surface since the guide was written:

• Login complete requires endUserIpAddress and returns sessionExpiresAt (feat(sca): return the session expiry and require an end-user IP on SCA login complete #780); the session guidance now tells integrators to prompt a re-login ahead of the expiry instead of discovering it on a failed call.
• Quote authorize documents 409 SCA_SESSION_REQUIRED and 423 ACCOUNT_LOCKED (feat: document SCA_SESSION_REQUIRED (409) and ACCOUNT_LOCKED (423) on quote authorize #761); both join the error tables, and the snippet notes that authorizing requires an active login session.
• Abandoned challenges now fail the transaction with failureReason: SCA_NOT_COMPLETED and no funds moved (Add SCA_NOT_COMPLETED outgoing transaction failure reason #762).
• Trusted external accounts refuse DELETE with 409 BENEFICIARY_TRUSTED — untrust (SCA-gated) before deleting (feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete #770).
• The challenge lives on the quote, not the transaction; webhook consumers route via the transaction's quoteId (docs: sync documentation with SCA schema changes #701). Fixed the "transaction (or quote) … scaChallenge" phrasing in the snippet, the flow-page blurbs, and the Mermaid authorize label.
• POST /transfer-out is deprecated in favor of POST /quotes with immediatelyExecute: true (docs: make /quotes the single transfer path, deprecate /transfer-in and /transfer-out #856); the transfer-out tab now says so.
• Corrected the suspension guidance to match the spec: a suspended customer clears the lockout by completing a password reset (RESET_PASSWORD_COMPLETED).

Review addressed

Incorporated the review on the guide:

• Bounded the 2FA-reset poll loop (stop at expiresAt / client timeout; restart if the window closes before liveness passes).
• Clarified the failed-login counter is cumulative and cleared only by RESET_PASSWORD_COMPLETED, not by a successful login.
• Untrust is documented as start → confirm, backed by the startBeneficiaryUntrust endpoint from feat(sca): SCA management surface — enrollment, login/session, beneficiary trust, 2FA reset #600.
• Fixed MD031/MD040 markdownlint violations on the new fenced code blocks.

Prose pass: em-dashes and AI-tell phrasing removed across the pages and the shared snippet.

Validation

• make build — rebundled openapi.yaml / mintlify/openapi.yaml byte-match main; the PR carries no spec changes.
• make lint (redocly + spectral) passes.
• markdownlint (repo-pinned markdownlint-cli) passes clean on all SCA pages and the touched flow pages.
• mint broken-links adds zero new broken links versus main.
• Two adversarial-review rounds: no P0/P1 findings; P2s fixed (authorize-call label in the Mermaid diagram, suspension-vs-password-reset wording, PENDING_AUTHORIZATION guard in the conversion example, type/factor discriminator wording).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Aug 29, 2026 1:03am
grid-wallet-demo	Ignored	Preview	Aug 29, 2026 1:03am

[jklein24]

• docs(sca): document Strong Customer Authentication for EU customers #683 👈 (View in Graphite)
• feat(sca): SCA management surface — enrollment, login/session, beneficiary trust, 2FA reset #600
• feat(sca): add Strong Customer Authentication surface #558
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jklein24]

@greptile review

[greptile-apps]

Greptile Summary

⚔ \m/ SCA documentation forged in EU steel \m/ ⚔ This PR adds a complete Strong Customer Authentication guide.

• Adds six pages covering authorization, factors, sessions, beneficiaries, and resets.
• Adds the SCA section to Mintlify navigation.
• Reuses one shared authorization snippet across payment flows.
• Guards realtime-funding instructions until quote authorization completes.
• Documents quote-scoped authorization, resend behavior, errors, and expiry.

Confidence Score: 5/5

This looks safe to merge.

• The pending quote example no longer reads withheld payment instructions.
• Authorization and resend guidance matches the quote-scoped API contract.
• No blocking issues remain in the updated documentation.

Important Files Changed

Filename	Overview
mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx	Guards access to realtime-funding payment instructions while authorization is pending.
mintlify/snippets/sca/strong-customer-authentication.mdx	Provides shared guidance for quote authorization, challenge loops, resend behavior, and expiry.
mintlify/platform-overview/sca/per-transaction-authorization.mdx	Documents authorization for prefunded and realtime-funded quotes.
mintlify/docs.json	Adds the six SCA pages to the documentation navigation.

_{Reviews (4): Last reviewed commit: "docs(sca): refresh the guide for API dri..." | Re-trigger Greptile}

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

Request changes

[github-actions]

✱ Stainless preview builds for grid

No changes were made to the SDKs.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-29 01:03:47 UTC

[jklein24]

Implementation follow-ups from the Striga SCA parity review (docs-only corrections are in b66552e):

1. Operation-aware factor support. Striga permits TOTP for non-dynamically-linked crypto withdrawals and trusted-beneficiary EUR/USDC sends, while dynamically linked debits require SMS/passkey. Grid needs to derive availableFactors from operation, destination, and trust state, expose a selectable factor where needed, and add contract tests for BTC/Lightning, trusted USDC, and untrusted regulated debits. Trust/untrust start must also accept a factor, or be documented and enforced as SMS-only; otherwise callers cannot initiate a passkey ceremony.

2. 2FA reset lifecycle. Grid returning 204 from completion plus independent re-enrollment does not model Striga factor-specific completion results, such as new TOTP material or passkey creation options, or the transition to COMPLETED only after enrollment confirmation. Either expose that continuation or prove the alternate flow with contract tests and a coherent status model; include pending-reset reuse, enrolled-factor mismatch, suspended-user recovery, and session-revocation behavior.

3. Strict proof contracts. Make authorization, login completion, and beneficiary-confirm schemas discriminated variants: exactly one proof, passkey requires assertion plus origin, and SMS requires challenge ID. Add negative validation tests so {} and invalid factor/proof combinations fail at schema validation.

4. Session enforcement. Confirm or implement the 180-day EUR/USDC read session, fresh SCA for history older than 90 days, and prior-session revocation on login. Surface deterministic Grid errors on the affected read endpoints.

Reference: https://docs.striga.com/reference/strong-customer-authentication-sca and https://docs.striga.com/reference/sca-factors-implementation.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 28, 2026, 7:15 AM

[ls-bolt]

⚡ Revision log — updated in place, latest first.

Revision 2

Rebased onto current main to clear merge conflicts: #877 ("Payout timing") and this PR both added a section after the status table in send-payment.mdx — resolved by keeping both sections (timing first, then SCA). Content is otherwise unchanged from the drift-refresh push; make build bundles still byte-match main, make lint and markdownlint pass.

Earlier revisions (1)

Revision 1

Rebased onto current main (dropped the already-merged #600 spec commits — the PR is now docs-only) and refreshed the guide for SCA-surface drift since the branch point:

• Login complete: documented required endUserIpAddress + new sessionExpiresAt response field (feat(sca): return the session expiry and require an end-user IP on SCA login complete #780)
• Error tables: added 409 SCA_SESSION_REQUIRED and 423 ACCOUNT_LOCKED on quote authorize (feat: document SCA_SESSION_REQUIRED (409) and ACCOUNT_LOCKED (423) on quote authorize #761)
• Documented SCA_NOT_COMPLETED for challenges that expire unsatisfied — no funds moved, create a new quote (Add SCA_NOT_COMPLETED outgoing transaction failure reason #762)
• Trusted beneficiaries: DELETE on a trusted account returns 409 BENEFICIARY_TRUSTED — untrust first (feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete #770)
• Corrected challenge placement throughout: it lives on the quote, not the transaction; webhooks route via quoteId (docs: sync documentation with SCA schema changes #701)
• Transfer-out tab reworked for the POST /transfer-out deprecation → POST /quotes + immediatelyExecute: true (docs: make /quotes the single transfer path, deprecate /transfer-in and /transfer-out #856)
• Fixed suspension guidance to match the spec: password reset (RESET_PASSWORD_COMPLETED) clears a suspension
• Fixed the Mermaid authorize label (no scaChallenge.id in the authorize body) and the PENDING_AUTHORIZATION guard in the conversion example

Validation: make build bundles byte-match main, make lint passes, repo-pinned markdownlint clean on all touched pages, mint broken-links adds zero new broken links vs main.