feat(sca): add Strong Customer Authentication surface

openapi/components/schemas/quotes/ExecuteQuoteRequest.yaml

@@ -0,0 +1,14 @@
+type: object
+description: >-
+ Optional body for executing a quote. Only needed to request a specific Strong
+ Customer Authentication factor (`scaFactor`) for the challenge this call
+ issues; omit the body entirely otherwise.
+properties:
+ scaFactor:
+ $ref: ../sca/ScaFactor.yaml
+ description: >-
+ Optional preferred factor for the Strong Customer Authentication challenge
+ this call issues. Only relevant for customers in a region where SCA is required
+ (e.g. EU); ignored otherwise. Valid values for a per-transaction challenge
+ are `SMS_OTP` (default) and `PASSKEY` — `TOTP` cannot carry the required
+ dynamic linking and is rejected here. Omit to default to `SMS_OTP`.

openapi/components/schemas/quotes/Quote.yaml

@@ -22,11 +22,17 @@ properties:
  type: string
  enum:
  - PENDING
+ - PENDING_AUTHORIZATION
  - PROCESSING
  - COMPLETED
  - FAILED
  - EXPIRED
- description: Current status of the quote
+ description: >-
+ Current status of the quote. `PENDING_AUTHORIZATION` occurs only for
+ customers in a region where Strong Customer Authentication is required (e.g.
+ EU): the quote carries an `scaChallenge` that must be authorized before
+ execution, and for realtime-funding sources `paymentInstructions` are
+ withheld until it is satisfied.
  example: PENDING
  createdAt:
  type: string
@@ -120,3 +126,11 @@ properties:
  rateDetails:
  $ref: ../transactions/OutgoingRateDetails.yaml
  description: Details about the rate and fees for the transaction.
+ scaChallenge:
+ $ref: ../sca/ScaChallenge.yaml
+ readOnly: true
+ description: >-
+ Present only while `status` is `PENDING_AUTHORIZATION`: the Strong
+ Customer Authentication challenge to satisfy before this quote can be
+ executed (or, for realtime-funding sources, before `paymentInstructions`
+ are issued). Omitted for customers outside SCA-regulated regions (non-EU).

openapi/components/schemas/quotes/QuoteRequest.yaml

@@ -57,6 +57,15 @@ properties:
  example: 'Invoice #1234 payment'
  purposeOfPayment:
  $ref: ./PurposeOfPayment.yaml
+ scaFactor:
+ $ref: ../sca/ScaFactor.yaml
+ description: >-
+ Optional preferred factor for a Strong Customer Authentication challenge
+ issued at quote creation. Only relevant for a realtime-funding source
+ in a region where SCA is required (e.g. EU); ignored otherwise. Valid values are
+ `SMS_OTP` (default) and `PASSKEY` — `TOTP` cannot carry the required
+ dynamic linking and is rejected. When the quote is returned in
+ `PENDING_AUTHORIZATION`, authorize it via `POST /quotes/{quoteId}/authorize`.
  senderCustomerInfo:
  type: object
  additionalProperties: true

openapi/components/schemas/sca/ScaAuthorization.yaml

@@ -0,0 +1,37 @@
+type: object
+description: >-
+ Proof that satisfies an `ScaChallenge`. Provide exactly one of `code` (for
+ `SMS_OTP` / `TOTP`) or `passkeyAssertion` (for `PASSKEY`). When supplying a
+ `passkeyAssertion`, `origin` is **required** — the WebAuthn assertion is bound
+ to the origin it was produced against, and a passkey confirmation is rejected
+ without it.
+properties:
+ code:
+ type:
+ - string
+ - 'null'
+ description: >-
+ The one-time code the customer received by SMS, or read from their
+ authenticator app. In sandbox, the code is always `123456`.
+ example: '123456'
+ passkeyAssertion:
+ type:
+ - object
+ - 'null'
+ additionalProperties: true
+ description: >-
+ Opaque WebAuthn assertion produced by the device from the challenge's
+ `passkeyAssertionOptions`. Required when satisfying a `PASSKEY` challenge.
+ origin:
+ type:
+ - string
+ - 'null'
+ description: >-
+ The WebAuthn origin the `passkeyAssertion` was produced against.
+ **Required** alongside `passkeyAssertion`; omit it for the `code` path.
+ When the challenge lists `passkeyAllowedOrigins` (enrollment / login
+ challenges), it must be one of those. A per-transaction passkey challenge
+ carries `passkeyAssertionOptions` but may omit `passkeyAllowedOrigins`; in
+ that case supply the origin your app invoked the WebAuthn API from, which
+ must match the relying party in `passkeyAssertionOptions`.
+ example: https://app.example.com

openapi/components/schemas/sca/ScaChallenge.yaml

@@ -0,0 +1,88 @@
+type: object
+description: >-
+ A Strong Customer Authentication challenge that must be satisfied before a
+ money-movement operation can complete. This object is **only present when the customer is in a region where SCA is required** (the EU); for customers outside SCA-regulated regions it is omitted
+ entirely and no action is needed.
+
+
+ When present on a quote, authorize it by submitting an `ScaAuthorization` proof
+ to `POST /quotes/{quoteId}/authorize`.
+
+
+ **A single operation may require more than one authorization, in sequence.**
+ Treat `scaChallenge` as *the challenge to satisfy now*, not "the only one".
+ After each authorize, re-inspect the returned quote/transaction: if it is
+ still `PENDING_AUTHORIZATION`, it carries the **next** `scaChallenge` (a new
+ `id`) — authorize that too, and repeat until it leaves `PENDING_AUTHORIZATION`.
+ Do not assume one authorization releases the transfer. The number of
+ authorizations is flow-dependent and **may decrease in future**:
+ for example, a cross-currency send today authorizes the currency conversion
+ and the payout as two separate challenges; a future update may
+ collapse them into one. A client written to loop on status handles any count
+ unchanged.
+required:
+ - id
+ - expiresAt
+ - factor
+ - availableFactors
+properties:
+ id:
+ type: string
+ description: >-
+ Unique identifier for this challenge. The server resolves the active
+ challenge from the quote or transaction being authorized, so this field
+ need not be supplied back; it is informational (e.g. for logging or
+ correlation).
+ example: ScaChallenge:019542f5-b3e7-1d02-0000-000000000007
+ expiresAt:
+ type: string
+ format: date-time
+ description: Absolute UTC timestamp after which this challenge can no longer be authorized.
+ example: '2025-10-03T12:05:00Z'
+ factor:
+ $ref: ./ScaFactor.yaml
+ description: The factor this challenge was issued for. Defaults to `SMS_OTP`.
+ availableFactors:
+ type: array
+ description: The factors the customer may use to satisfy this challenge.
+ items:
+ $ref: ./ScaFactor.yaml
+ example:
+ - SMS_OTP
+ purpose:
+ type:
+ - string
+ - 'null'
+ description: >-
+ Optional, informational label for what this particular challenge in the
+ sequence authorizes — useful for step UX (e.g. "Authorize the currency
+ conversion" vs "Authorize the payout"). Known values include
+ `CURRENCY_CONVERSION`, `PAYOUT`, and `TRANSFER`, but the set is
+ **non-exhaustive and may grow** — treat unrecognized values as a generic
+ authorization step and do not branch program logic on it. Omitted when steps are not distinguished (e.g. a single-authorization flow).
+ example: PAYOUT
+ passkeyAssertionOptions:
+ type:
+ - object
+ - 'null'
+ additionalProperties: true
+ description: >-
+ Opaque WebAuthn assertion request options (including the relying-party id,
+ challenge, and allowed credentials), present only when `factor` is
+ `PASSKEY`. Pass to the device's WebAuthn API to produce the assertion
+ submitted back in `ScaAuthorization.passkeyAssertion`.
+ passkeyAllowedOrigins:
+ type:
+ - array
+ - 'null'
+ items:
+ type: string
+ description: >-
+ The origins the WebAuthn ceremony may run against. Populated for
+ enrollment and login passkey challenges; the origin the assertion is
+ produced against must be one of these and echoed back as
+ `ScaAuthorization.origin`. Per-transaction passkey challenges omit this
+ (they carry `passkeyAssertionOptions` only) — see `ScaAuthorization.origin`
+ for how to source the origin in that case.
+ example:
+ - https://app.example.com

openapi/components/schemas/sca/ScaFactor.yaml

@@ -0,0 +1,13 @@
+type: string
+enum:
+ - SMS_OTP
+ - TOTP
+ - PASSKEY
+description: |
+ A Strong Customer Authentication factor.
+
+ | Factor | Description |
+ |--------|-------------|
+ | `SMS_OTP` | One-time code sent by SMS to the customer's verified phone. Requires no prior enrollment. |
+ | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). |
+ | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. |

openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml

@@ -1,6 +1,7 @@
 type: string
 enum:
  - PENDING
+ - PENDING_AUTHORIZATION
  - EXPIRED
  - PROCESSING
  - COMPLETED
@@ -11,6 +12,7 @@ description: |
  | Status | Description |
  |--------|-------------|
  | `PENDING` | Quote is pending confirmation |
+ | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU); authorize the transaction's `scaChallenge` to proceed. |
  | `EXPIRED` | Quote wasn't executed before expiry window |
  | `PROCESSING` | Executing the quote after receiving funds |
  | `COMPLETED` | Payout successfully reached the destination |

openapi/components/schemas/transactions/TransactionStatus.yaml

@@ -2,6 +2,7 @@ type: string
 enum:
  - CREATED
  - PENDING
+ - PENDING_AUTHORIZATION
  - PROCESSING
  - COMPLETED
  - REJECTED
@@ -15,6 +16,7 @@ description: |
  |--------|-------------|
  | `CREATED` | Initial lookup has been created |
  | `PENDING` | Quote has been created |
+ | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU); authorize the transaction's `scaChallenge` to proceed. |
  | `PROCESSING` | Funding has been received and payment initiated |
  | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network |
  | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded |

openapi/components/schemas/transfers/TransferOutRequest.yaml

@@ -26,3 +26,11 @@ properties:
  remittanceInformation field, and for wires it populates the OBI
  (Originator to Beneficiary Information) / beneficiary information.
  example: '12345'
+ scaFactor:
+ $ref: ../sca/ScaFactor.yaml
+ description: >-
+ Optional preferred factor for the Strong Customer Authentication challenge
+ this call issues. Only relevant for customers in a region where SCA is required
+ (e.g. EU); ignored otherwise. Valid values for a per-transaction challenge
+ are `SMS_OTP` (default) and `PASSKEY` — `TOTP` cannot carry the required
+ dynamic linking and is rejected here. Omit to default to `SMS_OTP`.

openapi/components/schemas/webhooks/OutgoingPaymentWebhook.yaml

@@ -10,6 +10,7 @@ allOf:
  type: string
  enum:
  - OUTGOING_PAYMENT.PENDING
+ - OUTGOING_PAYMENT.PENDING_AUTHORIZATION
  - OUTGOING_PAYMENT.PROCESSING
  - OUTGOING_PAYMENT.COMPLETED
  - OUTGOING_PAYMENT.FAILED

openapi/paths/quotes/quotes.yaml

@@ -115,6 +115,18 @@ post:
  exchangeRate: 0.92
  feesIncluded: 10
  transactionId: Transaction:019542f5-b3e7-1d02-0000-000000000005
+ '202':
+ description: >
+ Quote created but awaiting Strong Customer Authentication. Returned only
+ for customers whose provider requires SCA (e.g. EU) on a realtime-funding
+ source: the quote has status `PENDING_AUTHORIZATION` and carries an
+ `scaChallenge`, and `paymentInstructions` are **withheld** until the
+ challenge is authorized via `POST /quotes/{quoteId}/authorize`. Once
+ authorized, the quote's `paymentInstructions` are populated.
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/quotes/Quote.yaml
  '400':
  description: Bad request - Missing or invalid parameters
  content:

openapi/paths/quotes/quotes_{quoteId}_authorize.yaml

@@ -0,0 +1,87 @@
+parameters:
+ - name: quoteId
+ in: path
+ description: The unique identifier of the quote whose SCA challenge is being authorized.
+ required: true
+ schema:
+ type: string
+ example: Quote:019542f5-b3e7-1d02-0000-000000000006
+post:
+ summary: Authorize a quote's SCA challenge
+ description: |
+ Satisfy the Strong Customer Authentication challenge carried by a quote in
+ `PENDING_AUTHORIZATION` status by submitting an `ScaAuthorization` proof.
+
+ This is used for realtime-funding quotes: the quote is returned with an
+ `scaChallenge` and **without** `paymentInstructions`; once authorized, the
+ quote advances and its `paymentInstructions` are populated so the customer
+ can fund the transfer.
+
+ As with all SCA, a quote may require more than one authorization: after
+ authorizing, if the quote is still `PENDING_AUTHORIZATION` it carries the
+ next `scaChallenge` — authorize that too, repeating until it advances (see
+ `ScaChallenge`).
+
+ This endpoint is only meaningful for customers in a region where SCA is required (e.g. EU). For customers outside SCA-regulated regions, this returns `409`.
+
+ In sandbox, the SMS code is always `123456`.
+ operationId: authorizeQuote
+ tags:
+ - Strong Customer Authentication
+ security:
+ - BasicAuth: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/sca/ScaAuthorization.yaml
+ responses:
+ '200':
+ description: Challenge authorized; the updated quote is returned.
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/quotes/Quote.yaml
+ '400':
+ description: Invalid or expired authorization proof
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error400.yaml
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error401.yaml
+ '404':
+ description: Quote not found
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error404.yaml
+ '409':
+ description: >-
+ SCA is not required for this customer, or the quote has
+ no pending challenge to authorize.
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error409.yaml
+ '429':
+ description: >-
+ Too many requests. Returned with `RATE_LIMITED` when authorization
+ attempts for this challenge happen too frequently (for example, repeated
+ bad codes brute-forcing the OTP). The challenge may be invalidated after too many failed attempts. Clients should back off and
+ retry after the interval indicated by the `Retry-After` response header.
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error429.yaml
+ '500':
+ description: Internal service error
+ content:
+ application/json:
+ schema:
+ $ref: ../../components/schemas/errors/Error500.yaml