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

mintlify/docs.json

@@ -58,6 +58,17 @@
  "platform-overview/core-concepts/currencies-and-rails",
  "platform-overview/configuration"
  ]
+ },
+ {
+ "group": "Strong Customer Authentication",
+ "pages": [
+ "platform-overview/sca/overview",
+ "platform-overview/sca/per-transaction-authorization",
+ "platform-overview/sca/factor-enrollment",
+ "platform-overview/sca/login-and-sessions",
+ "platform-overview/sca/trusted-beneficiaries",
+ "platform-overview/sca/two-factor-reset"
+ ]
  }
  ]
  },

mintlify/global-p2p/sending-receiving-payments/sending-payments.mdx

@@ -25,4 +25,11 @@ import SendUMA from '/snippets/sending/uma.mdx'
 
 <SendUMA />
 
-
+## Strong Customer Authentication (EU customers)
+
+Customers in SCA-regulated regions (in practice the EU: EUR / USDC) must confirm
+payments with Strong Customer Authentication. When it applies, the quote comes
+back `PENDING_AUTHORIZATION` carrying an `scaChallenge` that you authorize
+before the transfer is released; for every other customer nothing changes. See
+[Per-transaction authorization](/platform-overview/sca/per-transaction-authorization)
+for the full walkthrough.

mintlify/payouts-and-b2b/payment-flow/send-payment.mdx

@@ -264,6 +264,15 @@ end-to-end times measured from quote execution:
  of these.
 </Info>
 
+## Strong Customer Authentication (EU customers)
+
+Customers in SCA-regulated regions (in practice the EU: EUR / USDC) must confirm
+payments with Strong Customer Authentication. When it applies, the quote comes
+back `PENDING_AUTHORIZATION` carrying an `scaChallenge` that you authorize
+before the transfer is released; for every other customer nothing changes. See
+[Per-transaction authorization](/platform-overview/sca/per-transaction-authorization)
+for the full walkthrough.
+
 ## Checking Payment Status
 
 Configure a webhook endpoint to receive real-time notifications when payment status changes:

mintlify/platform-overview/sca/factor-enrollment.mdx

@@ -0,0 +1,144 @@
+---
+icon: "/images/icons/key2.svg"
+title: "Factor enrollment"
+description: "Enroll and manage a customer's TOTP and passkey factors"
+"og:image": "/images/og/og-get-started.png"
+---
+
+<Note>
+Applies only to customers in an SCA-required region (EU). Every endpoint here
+returns **`409`** for other customers.
+</Note>
+
+`SMS_OTP` needs no enrollment; a code is sent to the customer's verified phone.
+`TOTP` and `PASSKEY` must be enrolled before a customer can authenticate with
+them. Enrolled factors then appear in `scaChallenge.availableFactors` and can be
+requested per transaction (see
+[per-transaction authorization](/platform-overview/sca/per-transaction-authorization)).
+
+Enrollment is two calls, both discriminated by a `type` field (`TOTP` or
+`PASSKEY`):
+
+- `POST /sca/factors` — start enrollment; returns the factor-specific material.
+- `POST /sca/factors/confirm` — finish enrollment with the factor-specific proof.
+
+All paths below are relative to `https://api.lightspark.com/grid/2025-10-13`.
+
+## Enroll a TOTP authenticator
+
+<Steps>
+<Step title="Start enrollment">
+
+```bash
+POST /sca/factors?customerId={customerId}
+
+{ "type": "TOTP" }
+```
+
+Returns the shared secret and an `otpauth://` provisioning URI. Render `totpUri`
+as a QR code (or show `secretBase32Encoded` for manual entry) so the customer can
+add it to their authenticator app.
+
+```json
+{
+ "type": "TOTP",
+ "secret": "…",
+ "secretBase32Encoded": "ABC123…",
+ "totpUri": "otpauth://totp/Grid:customer@example.com?secret=ABC123&issuer=Grid"
+}
+```
+
+</Step>
+<Step title="Confirm enrollment">
+Submit the `secret` from the start call plus the first code the app produces.
+Grid returns one-time **recovery codes**; surface them to the customer once and
+don't store them server-side.
+
+```bash
+POST /sca/factors/confirm?customerId={customerId}
+
+{ "type": "TOTP", "secret": "…", "code": "123456" }
+```
+
+```json
+{ "type": "TOTP", "recoveryCodes": ["ABCD-EFGH-IJKL", "MNOP-QRST-UVWX"] }
+```
+
+A wrong or expired code returns `400`. **In sandbox, the code is always
+`123456`.**
+</Step>
+</Steps>
+
+## Enroll a passkey
+
+Passkey enrollment is a standard WebAuthn registration ceremony. Grid issues the
+options, the customer's device produces the credential, and you hand it back.
+
+<Note>
+A customer may have **only one passkey**. If one is already enrolled, starting
+another returns `409` (`PASSKEY_ALREADY_ENROLLED`) — delete the existing passkey
+first (see below). `GET /sca/factors` therefore lists at most one passkey.
+</Note>
+
+<Steps>
+<Step title="Start enrollment">
+
+```bash
+POST /sca/factors?customerId={customerId}
+
+{ "type": "PASSKEY" }
+```
+
+```json
+{
+ "type": "PASSKEY",
+ "options": { "…": "opaque WebAuthn PublicKeyCredentialCreationOptions" },
+ "allowedOrigins": ["https://app.example.com"],
+ "relyingPartyId": "app.example.com"
+}
+```
+
+Pass `options` unmodified to the device's WebAuthn API
+(`navigator.credentials.create`). The ceremony must run against one of
+`allowedOrigins`.
+</Step>
+<Step title="Confirm enrollment">
+Submit the credential the device produced and the `origin` it ran against.
+
+```bash
+POST /sca/factors/confirm?customerId={customerId}
+
+{ "type": "PASSKEY", "origin": "https://app.example.com", "credential": { "…": "opaque WebAuthn credential" } }
+```
+
+Returns the enrolled `factor` (an `ScaFactorView`, including the `credentialId`
+you'll use to delete it later). An invalid credential or origin returns `400`.
+</Step>
+</Steps>
+
+## List enrolled factors
+
+```bash
+GET /sca/factors?customerId={customerId}
+```
+
+```json
+{
+ "factors": [
+ { "factor": "TOTP", "name": "Authenticator app" },
+ { "factor": "PASSKEY", "credentialId": "…", "name": "iPhone" }
+ ]
+}
+```
+
+`credentialId` is populated only for `PASSKEY` factors.
+
+## Delete a factor
+
+```bash
+DELETE /sca/factors/{credentialId}?customerId={customerId}
+```
+
+Returns `204`. Use the `credentialId` from the factor list (or the confirm
+response). Today only passkeys carry a `credentialId`, so this is how you remove
+an enrolled passkey.

mintlify/platform-overview/sca/login-and-sessions.mdx

@@ -0,0 +1,131 @@
+---
+icon: "/images/icons/shield.svg"
+title: "Login & sessions"
+description: "The end-user SCA login and the session it grants"
+"og:image": "/images/og/og-get-started.png"
+---
+
+<Note>
+Applies only to customers in an SCA-required region (EU). Every endpoint here
+returns **`409`** for other customers.
+</Note>
+
+Per-transaction authorization gates individual debits. The **SCA login** is
+separate: it authenticates the end user to open a longer-lived session that
+covers reads and account access beyond the per-transaction window. Grid provides
+the login plumbing; your application decides when to drive it (for example, when
+a customer opens their account and the previous session has lapsed).
+
+<Note>
+**A customer's EUR / USDC accounts aren't provisioned until their first SCA
+login after KYC approval.** Provisioning is deferred from KYC-approval time to
+the first login that opens a valid SCA session, so a freshly KYC-approved
+customer's EUR / USDC accounts won't appear in `GET /customers/internal-accounts`
+until then. Expect those accounts to be unavailable, and drive the SCA login
+once KYC is approved, before relying on them.
+</Note>
+
+All paths below are relative to `https://api.lightspark.com/grid/2025-10-13`.
+
+## Logging in
+
+<Steps>
+<Step title="Start the login">
+
+```bash
+POST /sca/login/start?customerId={customerId}
+
+{ "factor": "SMS_OTP" }
+```
+
+The response carries only what the chosen factor needs:
+
+- **`SMS_OTP`**: a code is dispatched; you get back `challengeId` and `expiresAt`.
+- **`TOTP`**: nothing extra; the customer reads the code from their app.
+- **`PASSKEY`**: WebAuthn `passkeyOptions` (with `allowedOrigins` and `relyingPartyId`) to pass to the device.
+
+The factor must already be enrolled (or, for `SMS_OTP`, the phone verified). See
+[factor enrollment](/platform-overview/sca/factor-enrollment).
+</Step>
+<Step title="Complete the login">
+Submit the proof for the factor you started with: `code` for `SMS_OTP` / `TOTP`
+(echoing `challengeId` for `SMS_OTP`), or `passkeyAssertion` + `origin` for
+`PASSKEY`. Every completion also requires **`endUserIpAddress`** — the IP of the
+end user's device the login is performed from, recorded against the login event
+and fed into risk assessment. Supply the customer's address, not your server's.
+
+```bash
+POST /sca/login/complete?customerId={customerId}
+
+{ "factor": "SMS_OTP", "challengeId": "…", "code": "123456", "endUserIpAddress": "203.0.113.42" }
+```
+
+```json
+{ "status": "SUCCESS", "sessionExpiresAt": "2026-01-29T12:00:00Z" }
+```
+
+A `status` of `SUCCESS` opens the session and revokes any previous SCA session
+for that customer, and `sessionExpiresAt` gives its absolute expiry — prompt a
+re-login ahead of it rather than waiting for a call to fail. Any other `status`
+value means the login did not complete; treat only `SUCCESS` as success. An
+invalid or expired proof — or a missing or malformed `endUserIpAddress` —
+returns `400`. **In sandbox, the code is always `123456`.**
+</Step>
+</Steps>
+
+## Session scope and fresh authentication
+
+An active SCA login session covers EUR / USDC account reads for 180 days; the
+login-complete response's `sessionExpiresAt` gives the exact timestamp it
+lapses. A request for transaction history older than 90 days requires fresh SCA,
+even when the broader session has not expired. Money movement in SCA-regulated
+currencies is refused with **`409` `SCA_SESSION_REQUIRED`** once the session
+passes, so track `sessionExpiresAt` and drive a re-login before it does. When
+Grid indicates that a session is missing, expired, or too old for the requested
+history, restart the login flow before retrying the read.
+
+## Account-security signals
+
+Grid runs an adaptive-authentication risk engine that maintains each customer's
+login-security state. Because your application owns the customer's login, you
+report the security-relevant events it sees so the engine can act on them:
+
+```bash
+POST /sca/record-event?customerId={customerId}
+
+{ "eventType": "FAILED_LOGIN_ATTEMPT" }
+```
+
+Returns the customer's resulting login-security state so you can surface a
+lockout — `{ eventType, suspended, lockedUntil, failedAttempts }`. When the
+customer is locked out, this endpoint, `POST /sca/login/complete`, and
+[quote authorization](/platform-overview/sca/per-transaction-authorization)
+return `423` with `details.lockedUntil` (when they may retry) and
+`details.failedAttempts`.
+`eventType` must be one of:
+
+| `eventType` | Effect |
+|---|---|
+| `FAILED_LOGIN_ATTEMPT` | Increments the failed-login counter and escalates a lockout: **5 → 15 min, 6 → 30 min, 7 → 1 hour, 8 → 24 hours, 9 or more → suspension.** |
+| `RESET_PASSWORD_COMPLETED` | Revokes every active SCA session for the customer and clears the failed-login counter. |
+
+Report `FAILED_LOGIN_ATTEMPT` on each failed sign-in and `RESET_PASSWORD_COMPLETED`
+once a password recovery finishes. Any other value returns `400`.
+
+<Note>
+The failed-login counter is cumulative and is **not** reset by a successful
+login; only `RESET_PASSWORD_COMPLETED` clears it. Record that event after a
+password recovery to zero the counter and clear a time-bounded lockout, rather
+than relying on the customer simply logging in again. A suspended customer
+(9 or more failed attempts, locked with no automatic expiry) clears the
+suspension the same way — a completed password reset.
+</Note>
+
+## Your responsibilities
+
+Grid provides the SCA endpoints and risk decisions; your application owns the
+end-user login and session experience. Report every failed sign-in and completed
+password recovery through `record-event`, enforce any returned lockout before
+offering another login attempt, and do not store or reuse a customer's TOTP
+secret or passkey material. Treat TOTP secrets and WebAuthn ceremony data as
+end-user credentials, not platform credentials.