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

@@ -27,4 +27,13 @@ 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 payment comes
+back `PENDING_AUTHORIZATION` with 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

@@ -362,6 +362,15 @@ If a transaction fails, Grid initiates a refund automatically. You'll receive `O
 | `FAILED`     | Transfer failed — refund initiated automatically (track via `refund` object) |
 | `EXPIRED`    | Quote expired without execution            |
 
+## 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 payment comes
+back `PENDING_AUTHORIZATION` with 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,145 @@
+---
+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`) — the same shape the [login and session](/platform-overview/sca/login-and-sessions)
+endpoints use:
+
+- `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,103 @@
+---
+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`.
+
+```bash
+POST /sca/login/complete?customerId={customerId}
+
+{ "factor": "SMS_OTP", "challengeId": "…", "code": "123456" }
+```
+
+```json
+{ "status": "SUCCESS" }
+```
+
+A `status` of `SUCCESS` means the session is open. Any other value means the
+login did not complete; the field is passed through verbatim, so treat only
+`SUCCESS` as success. An invalid or expired proof returns `400`. **In sandbox,
+the code is always `123456`.**
+</Step>
+</Steps>
+
+## 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 (and `POST /sca/login/complete`) returns `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 lift a lockout, rather than relying on
+the customer simply logging in again.
+</Note>