---
title: "Authorize a quote's SCA challenge"
method: POST
path: "/quotes/{quoteId}/authorize"
tags: ["Strong Customer Authentication"]
---

# Authorize a quote's SCA challenge

`POST /quotes/{quoteId}/authorize`

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`.

## Request body

- ScaAuthorization — 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.
  - `code` string, nullable — The one-time code the customer received by SMS, or read from their authenticator app. In sandbox, the code is always `123456`.
  - `passkeyAssertion` object, nullable — Opaque WebAuthn assertion produced by the device from the challenge's `passkeyAssertionOptions`. Required when satisfying a `PASSKEY` challenge.
  - `origin` string, nullable — 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`.
  - `endUserIpAddress` string, nullable — The IP address of the end user's device authorizing this operation, forwarded to the SCA provider where it feeds risk assessment and any transaction-risk exemption. Supply the customer's address, not your server's. Optional: the provider records it for money-movement authorizations, and ignores it for beneficiary trust changes.

## Response `200`

Challenge authorized; the updated quote is returned.

- Quote
  - `id` string, required — Unique identifier for this quote
  - `status` 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — 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.
  - `createdAt` string, date-time, required — When this quote was created
  - `expiresAt` string, date-time, required — Absolute UTC timestamp when the rate locked in this quote becomes invalid and the quote can no longer be executed. The window depends on the rail and corridor: instant rails (Lightning, Spark, USDC on Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5 minutes; corridors with longer settlement guarantees may have longer windows. Always rely on this timestamp rather than assuming a fixed window.
  - `source` union, required
    - AccountQuoteSource — Source account details
      - `sourceType` 'ACCOUNT', required — Type of quote funding source
      - `accountId` string, required — Source account identifier
      - `customerId` string — Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated. Otherwise, will default to the customerId of the account owner.
    - RealtimeFundingQuoteSource — Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.).
      - `sourceType` 'REALTIME_FUNDING', required — Type of quote funding source
      - `customerId` string — Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself.
      - `currency` string, required — Currency code for the funding source. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
      - `cryptoNetwork` string — The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `TRON`, `PLASMA`, `SPARK`, `LIGHTNING`, `BITCOIN`.
  - `destination` union, required
    - AccountDestination — Destination account details
      - `destinationType` 'ACCOUNT', required — Type of payment destination
      - `accountId` string, required — Destination account identifier
      - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail.
    - UmaAddressDestination — UMA address destination details
      - `destinationType` 'UMA_ADDRESS', required — Type of payment destination
      - `umaAddress` string, required — UMA address of the recipient
      - `currency` string — Currency code for the destination. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
  - `sendingCurrency` Currency, required
    - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
    - `name` string — Full name of the currency
    - `symbol` string — Symbol of the currency
    - `decimals` integer — Number of decimal places for the currency
  - `receivingCurrency` Currency, required
    - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
    - `name` string — Full name of the currency
    - `symbol` string — Symbol of the currency
    - `decimals` integer — Number of decimal places for the currency
  - `totalSendingAmount` integer, required — The total amount that will be sent in the smallest unit of the sending currency (eg. cents).
  - `totalReceivingAmount` integer, required — The total amount that will be received in the smallest unit of the receiving currency (eg. cents).
  - `exchangeRate` number, required — Number of sending currency units per receiving currency unit.
  - `feesIncluded` integer, required — The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.
  - `platformFeesIncluded` integer — The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. May be omitted from payloads produced before platform fees existed.
  - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. This is not required when using an internal account source. — unresolved $ref
  - `transactionId` string, required — The ID of the transaction created from this quote.
  - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
  - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.
    - `counterpartyMultiplier` number, double, required — The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution.
    - `counterpartyFixedFee` integer, required — The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents).
    - `gridApiMultiplier` number, double, required — The underlying multiplier from the sending currency to mSATS, including variable fees.
    - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents).
    - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount.
    - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate.
  - `scaChallenge` ScaChallenge — 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.
    - `id` string, required — 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).
    - `expiresAt` string, date-time, required — Absolute UTC timestamp after which this challenge can no longer be authorized.
    - `factor` 'SMS_OTP' | 'TOTP' | 'PASSKEY', required — 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. |
    - `availableFactors` ScaFactor[], required — The factors the customer may use to satisfy this challenge.
    - `purpose` string, nullable — 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).
    - `passkeyAssertionOptions` object, nullable — 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` string[], nullable — 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.

## Other responses

- `400` — Invalid or expired authorization proof
- `401` — Unauthorized
- `404` — Quote not found
- `409` — SCA is not required for this customer, or the quote has no pending challenge to authorize. Also returned with `SCA_SESSION_REQUIRED` when the customer's SCA login session is missing or expired — re-authenticate the customer, then authorize again.
- `423` — Returned with `ACCOUNT_LOCKED` when the customer's login is temporarily locked after too many failed authorization attempts. The customer must wait for the lock to expire before authorizing again.
- `429` — 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.
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/27ff0fdca01c/schema)