Skip to content

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

Draft
jklein24 wants to merge 7 commits into
feat/striga-sca-managementfrom
feat/striga-sca-docs
Draft

docs(sca): document Strong Customer Authentication for EU customers#683
jklein24 wants to merge 7 commits into
feat/striga-sca-managementfrom
feat/striga-sca-docs

Conversation

@jklein24

@jklein24 jklein24 commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

Summary

A full, EU-scoped Strong Customer Authentication guide in the Mintlify docs. Stacks on #600 and documents the SCA surface added in #558/#600. 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.

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 now documented as start → confirm — backed by the new startBeneficiaryUntrust endpoint added to feat(sca): SCA management surface — enrollment, login/session, beneficiary trust, 2FA reset #600 (previously SMS/passkey had no way to obtain the untrust challenge).
  • 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

  • markdownlint-cli2 passes clean on all SCA pages.
  • mint broken-links adds zero new broken links (pre-existing ones are unrelated and untouched).

🤖 Generated with Claude Code

@vercel

vercel Bot commented Jul 13, 2026

Copy link
Copy Markdown

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

2 Skipped Deployments
Project Deployment Actions Updated (UTC)
grid-flow-builder Ignored Ignored Preview Jul 16, 2026 8:04pm
grid-wallet-demo Ignored Ignored Preview Jul 16, 2026 8:04pm

Request Review

Copy link
Copy Markdown
Contributor Author

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

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

@jklein24

Copy link
Copy Markdown
Contributor Author

@greptile review

@greptile-apps

greptile-apps Bot commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

⚔️ SCA OR FACE THE VOID ⚔️ \m/ (ಠ益ಠ) \m/

This PR documents Strong Customer Authentication for EU money movement. The main changes are:

  • Adds a reusable SCA guide covering factors, authorization loops, resend flows, and trusted beneficiaries.
  • Includes the guide in three relevant payment and conversion pages.
  • Guards realtime-funding instructions until SCA authorization completes.
  • Documents separate resend endpoints for transactions and quotes.

Confidence Score: 5/5

This looks safe to merge.

  • The realtime-funding example no longer reads withheld payment instructions.
  • The resend guide now includes the quote-scoped endpoint.
  • The shared snippet imports follow existing MDX conventions.
  • No blocking issues remain in the changed code.

Important Files Changed

Filename Overview
mintlify/snippets/sca/strong-customer-authentication.mdx Adds the reusable EU SCA guide and documents both quote- and transaction-scoped authorization flows.
mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx Adds the SCA guide and prevents access to withheld payment instructions while authorization is pending.
mintlify/payouts-and-b2b/payment-flow/send-payment.mdx Adds the shared SCA section to the payment flow.
mintlify/global-p2p/sending-receiving-payments/sending-payments.mdx Adds the shared SCA section to the global P2P payment flow.

Reviews (3): Last reviewed commit: "docs(sca): guard the fiat-to-crypto paym..." | Re-trigger Greptile

Comment thread mintlify/snippets/sca/strong-customer-authentication.mdx
Comment thread mintlify/snippets/sca/strong-customer-authentication.mdx Outdated
jklein24 added a commit that referenced this pull request Jul 13, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24

Copy link
Copy Markdown
Contributor Author

@greptile review

Comment thread mintlify/snippets/sca/strong-customer-authentication.mdx Outdated
jklein24 added a commit that referenced this pull request Jul 13, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24

Copy link
Copy Markdown
Contributor Author

@greptile review

@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from af68ac7 to d71d44d Compare July 14, 2026 06:29
jklein24 added a commit that referenced this pull request Jul 14, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 14, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from b6d2de5 to 2280c96 Compare July 14, 2026 06:29
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from d71d44d to 7ddda22 Compare July 14, 2026 06:37
jklein24 added a commit that referenced this pull request Jul 14, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 14, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from 2280c96 to 36e9188 Compare July 14, 2026 06:37
jklein24 added a commit that referenced this pull request Jul 14, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 14, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch 2 times, most recently from d61ee03 to 0d87524 Compare July 14, 2026 08:23

@jklein24 jklein24 left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes

Comment thread mintlify/platform-overview/sca/trusted-beneficiaries.mdx Outdated
Comment thread mintlify/platform-overview/sca/two-factor-reset.mdx Outdated
Comment thread mintlify/platform-overview/sca/login-and-sessions.mdx
Comment thread mintlify/platform-overview/sca/login-and-sessions.mdx
jklein24 added a commit that referenced this pull request Jul 14, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 14, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from 78c7440 to a3a6b90 Compare July 14, 2026 17:20
Comment thread mintlify/platform-overview/sca/per-transaction-authorization.mdx
Comment thread mintlify/payouts-and-b2b/payment-flow/send-payment.mdx Outdated
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from a3a6b90 to ccbe1bb Compare July 15, 2026 17:03
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from 2843a5c to 349f1d0 Compare July 15, 2026 20:11
jklein24 added a commit that referenced this pull request Jul 15, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 15, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from ccbe1bb to bdbce2c Compare July 15, 2026 20:11
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from 349f1d0 to 65c265a Compare July 16, 2026 07:32
jklein24 added a commit that referenced this pull request Jul 16, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 16, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from bdbce2c to 11115ef Compare July 16, 2026 07:33
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from 65c265a to b55685f Compare July 16, 2026 07:49
jklein24 added a commit that referenced this pull request Jul 16, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 16, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from 11115ef to 34c3e22 Compare July 16, 2026 07:49
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from b55685f to b906634 Compare July 16, 2026 08:26
jklein24 added a commit that referenced this pull request Jul 16, 2026
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
jklein24 added a commit that referenced this pull request Jul 16, 2026
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from 34c3e22 to be5713d Compare July 16, 2026 08:26
jklein24 and others added 7 commits July 16, 2026 12:02
Add an EU-scoped SCA section to the money-movement guides where it's relevant —
payouts send-payment, global-p2p sending-payments, and ramps fiat/crypto
conversion — via a reusable snippet. Mirrors Striga's SCA docs, adapted to
Grid's surface: when a transaction/quote comes back PENDING_AUTHORIZATION with
an scaChallenge, satisfy it through the authorize endpoints in a status-driven
loop (may be more than one), covering the SMS/passkey factors, inline
scaAuthorization, resend, sandbox 123456, and trusted-beneficiary. Scoped so
non-EU integrators have nothing to do.

Co-Authored-By: Claude <noreply@anthropic.com>
Address Greptile review on #683:
- Document the quote resend endpoint (POST /quotes/{quoteId}/authorize/resend)
  alongside the transaction one, since a realtime-funding quote's SMS challenge
  exists before any transaction.
- Note that a realtime-funding 202 withholds paymentInstructions until the
  challenge is authorized, so integrators authorize first, then read them.

Co-Authored-By: Claude <noreply@anthropic.com>
…CA-pending quotes

The runnable displayPaymentInstructions example dereferenced
quote.paymentInstructions[0] unconditionally, which throws for an EU
realtime-funding quote returned as PENDING_AUTHORIZATION (instructions withheld
until the scaChallenge is authorized). Guard for the pending case and point at
the SCA section. Addresses Greptile P1 on #683.

Co-Authored-By: Claude <noreply@anthropic.com>
Match the #558/#600 terminology fix in the embedded SCA docs section: 'customers
in a region where SCA is required (EU)' / 'customers outside SCA-regulated
regions' instead of 'whose payment provider requires SCA'.

Co-Authored-By: Claude <noreply@anthropic.com>
Grows the SCA docs from a single per-transaction snippet into a dedicated
"Strong Customer Authentication" guide covering the whole EU surface the API
exposes, mirroring the structure of the reference docs it wraps.

- overview: region scope, a "what SCA covers" coverage table, factors +
  dynamic-linking, a Mermaid flow diagram, lifetimes/limits and error tables,
  and navigation cards.
- per-transaction-authorization: reuses the existing snippet as the single
  source (flow pages unchanged).
- factor-enrollment: TOTP + passkey enrollment, list, delete.
- login-and-sessions: SCA login + the session it grants, plus account-security
  (record-event) signals and the lockout ladder.
- trusted-beneficiaries: start / confirm / untrust walkthrough (keyed by
  externalAccountId).
- two-factor-reset: liveness-gated reset (start -> poll -> complete).

All EU-scoped; every endpoint 409s for non-SCA customers.
- two-factor-reset: give the poll loop a bounded stop condition (stop at
  expiresAt / a client timeout; start a new reset if the window closes before
  liveness passes) instead of implying an open-ended wait.
- login-and-sessions: note the failed-login counter is cumulative and cleared
  only by RESET_PASSWORD_COMPLETED, not by a successful login.
- trusted-beneficiaries: untrust has no start step, so document that it's
  confirmed with a self-produced proof (TOTP) and challengeId is omitted;
  SMS/passkey untrust would need a start endpoint that isn't in the surface yet.
- fix MD031/MD040 markdownlint violations on the new fenced code blocks.
Now that startBeneficiaryUntrust exists, untrust mirrors trust (start issues the
challenge, confirm submits the proof), so drop the earlier note about untrust
having no start step.
@jklein24
jklein24 force-pushed the feat/striga-sca-management branch from b906634 to 94e5d2f Compare July 16, 2026 20:04
@jklein24
jklein24 force-pushed the feat/striga-sca-docs branch from be5713d to 4ea44c2 Compare July 16, 2026 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant