Authorize a quote's SCA challenge

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": "123456",
  "passkeyAssertion": {},
  "origin": "https://app.example.com"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({code: '123456', passkeyAssertion: {}, origin: 'https://app.example.com'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/authorize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"code\": \"123456\",\n  \"passkeyAssertion\": {},\n  \"origin\": \"https://app.example.com\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/authorize")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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",
  "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"
      }
    }
  ],
  "remittanceInformation": "12345",
  "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
  },
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  }
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "message": "<string>",
  "details": {}
}

{
  "status": 429,
  "code": "RATE_LIMITED",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Strong Customer Authentication

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

POST

quotes

{quoteId}

authorize

Authorize a quote's SCA challenge

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": "123456",
  "passkeyAssertion": {},
  "origin": "https://app.example.com"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({code: '123456', passkeyAssertion: {}, origin: 'https://app.example.com'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/authorize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"code\": \"123456\",\n  \"passkeyAssertion\": {},\n  \"origin\": \"https://app.example.com\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/authorize")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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",
  "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"
      }
    }
  ],
  "remittanceInformation": "12345",
  "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
  },
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  }
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "message": "<string>",
  "details": {}
}

{
  "status": 429,
  "code": "RATE_LIMITED",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

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

Example:

"123456"

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"

Response

Challenge authorized; the updated quote is returned.

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.

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"

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"
    }
  }
]

remittanceInformation

string

Free-form information about the payment that travels with it to the recipient, as provided on the quote request. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information.

Maximum string length: 80

Example:

"12345"

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

scaChallenge

object

read-only

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

Estimate crypto withdrawal fee

Resend a quote's SCA challenge code

⌘I

Using the API

API documentation

Authorize a quote's SCA challenge

Authorizations

Path Parameters

Body

Response