Authorize a quote's SCA challenge

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

POST /quotes/{quoteId}/authorize

Authorize a quote's SCA challenge

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/authorize \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "000000",
  "passkeyAssertion": {},
  "origin": "https://app.example.com",
  "endUserIpAddress": "203.0.113.42"
}
'

200

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "paymentRail": "ACH"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "totalSendingAmount": 123010,
  "totalReceivingAmount": 1000,
  "exchangeRate": 123,
  "feesIncluded": 10,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "platformFeesIncluded": 5,
  "paymentInstructions": [
    {
      "accountOrWalletInfo": {
        "accountType": "USD_ACCOUNT",
        "paymentRails": [
          "ACH",
          "WIRE"
        ],
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "bankName": "Chase Bank",
        "reference": "UMA-Q12345-REF"
      },
      "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
    },
    {
      "accountOrWalletInfo": {
        "accountType": "SPARK_WALLET",
        "assetType": "BTC",
        "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
        "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
      }
    }
  ],
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  },
  "purposeOfPayment": "GIFT",
  "documentIds": [
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "factor": "SMS_OTP",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  }
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

quoteId · string · required

The unique identifier of the quote whose SCA challenge is being authorized.

Body

application/json

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 | null

The one-time code the customer received by SMS, or read from their authenticator app. In sandbox, the code is always 000000.

Example:

"000000"

passkeyAssertion · object | null

Opaque WebAuthn assertion produced by the device from the challenge's passkeyAssertionOptions. Required when satisfying a PASSKEY challenge.

origin · string | null

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"

endUserIpAddress · string | null

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.

Example:

"203.0.113.42"

Response

200

application/json

Challenge authorized; the updated quote is returned.

id · string · required

Unique identifier for this quote

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"

status · enum<string> · 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.

Available options: PENDING, PENDING_AUTHORIZATION, PROCESSING, COMPLETED, FAILED, EXPIRED

Example:

"PENDING"

createdAt · string<date-time> · required

When this quote was created

Example:

"2025-10-03T12:00:00Z"

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.

Example:

"2025-10-03T12:05:00Z"

source · Account · object · required

Source account details

Account

Real-time Funding

Show child attributes

destination · Account · object · required

Destination account details

Account

UMA Address

Show child attributes

sendingCurrency · object · required

Currency for the sending amount

Show child attributes

receivingCurrency · object · required

Currency for the receiving amount

Show child attributes

totalSendingAmount · integer<int64> · required

The total amount that will be sent in the smallest unit of the sending currency (eg. cents).

Example:

123010

totalReceivingAmount · integer<int64> · required

The total amount that will be received in the smallest unit of the receiving currency (eg. cents).

Example:

1000

exchangeRate · number · required

Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts feesIncluded from totalSendingAmount first, then converts the remainder at this rate to reach totalReceivingAmount.

feesIncluded · integer<int64> · 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.

Required range: x >= 0

Example:

10

transactionId · string · required

The ID of the transaction created from this quote.

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000005"

platformFeesIncluded · integer<int64>

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.

Required range: x >= 0

Example:

5

paymentInstructions · object[]

Payment instructions for executing the payment. This is not required when using an internal account source.

Show child attributes

Example:

[
  {
    "accountOrWalletInfo": {
      "accountType": "USD_ACCOUNT",
      "paymentRails": ["ACH", "WIRE"],
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "reference": "UMA-Q12345-REF"
    },
    "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
  },
  {
    "accountOrWalletInfo": {
      "accountType": "SPARK_WALLET",
      "assetType": "BTC",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  }
]

counterpartyInformation · object

Additional information about the counterparty, if available and required by the platform in their configuration.

Example:

{
  "FULL_NAME": "John Sender",
  "BIRTH_DATE": "1985-06-15",
  "NATIONALITY": "DE"
}

rateDetails · object

Details about the rate and fees for the transaction.

Show child attributes

purposeOfPayment · enum<string>

The purpose of payment the quote was created with. Present only when the quote request set purposeOfPayment.

Available options: GIFT, SELF, GOODS_OR_SERVICES, EDUCATION, HEALTH_OR_MEDICAL, REAL_ESTATE_PURCHASE, TAX_PAYMENT, LOAN_PAYMENT, UTILITY_BILL, DONATION, TRAVEL, FAMILY_SUPPORT, SALARY_PAYMENT, EXPORTED_GOODS_PREPAYMENT, EXPORTED_GOODS_POSTPAYMENT, SERVICE_CHARGES, OFFICE_EXPENSES, DELIVERY_FEES, HOTEL_ACCOMMODATION, COMMISSION_ON_GOODS, COMMISSION_ON_SERVICES, ACCOUNTING_SERVICES, EXHIBITION_SERVICES, OTHER

documentIds · string[]

IDs of the supporting documents attached to the payment behind this quote, as passed in documentIds on POST /quotes. Present only when the quote was created with documentIds. Grid returns such a quote only after it has attached every document. Call GET /payment-documents/{paymentDocumentId} for each document's details, such as its documentType and its ATTACHED status.

Example:

[
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
]

scaChallenge · object

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

Show child attributes