Retry an incomplete payment

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/retry \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "senderCustomerInfo": {
    "FULL_NAME": "Jane Receiver",
    "NATIONALITY": "FR"
  }
}
'

{
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "accountId": "InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "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": [
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "referenceCode": "REF123456"
    },
    {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  ],
  "originalQuoteId": "Quote:019542f5-b3e7-1d02-0000-000000000001",
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  }
}

Cross-Currency Transfers

Retry an incomplete payment

In the case where a customer is debited but the Lightning payment fails to complete, integrators can retry the payment using this endpoint.

Payments retried with this endpoint will debit from the sender and deliver to the recipient the same amount as the original quote. As the Grid API does not persist customer PII, retries need to start with a lookup request to retrieve the original quote’s recipient counter party data requirements then pass that sender information in the request body. Before calling this endpoint, you should reach out to the Lightspark team to investigate the underlying issue. As part of resolution, they’ll update the transaction to the appropriate state. The quote / transaction to retry must be in a FAILED or REFUNDED state.

POST

quotes

{quoteId}

retry

Retry an incomplete payment

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/retry \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "senderCustomerInfo": {
    "FULL_NAME": "Jane Receiver",
    "NATIONALITY": "FR"
  }
}
'

{
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "accountId": "InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "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": [
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "referenceCode": "REF123456"
    },
    {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  ],
  "originalQuoteId": "Quote:019542f5-b3e7-1d02-0000-000000000001",
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

quoteId

string

required

ID of the quote to retry

Body

application/json

lookupId

string

required

Unique identifier for the prior receiver uma address lookup request.

Example:

"Lookup:019542f5-b3e7-1d02-0000-000000000009"

senderCustomerInfo

object

Key-value pairs of information about the sender which was requested by the counterparty (recipient) institution. Any fields specified in requiredPayerDataFields from the response of the /receiver/{receiverUmaAddress} (lookupUma) endpoint MUST be provided here if they were requested. If the counterparty (recipient) institution did not request any information, this field can be omitted.

Example:

{
  "FULL_NAME": "Jane Receiver",
  "NATIONALITY": "FR"
}

Response

Quote created successfully. The response includes payment instructions that the client can use to execute the payment through their banking provider.

quoteId

string

required

Unique identifier for this quote

Example:

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

status

enum<string>

required

Current status of the quote

Available options:

PENDING,

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

When this quote expires (typically 1-5 minutes after creation)

Example:

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

source

Account · object

required

Source account details

Account
Real-time funding

Show child attributes

source.accountId

string

required

Source account identifier

Example:

"InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

source.currency

string

Currency code for the source account

Example:

"USD"

destination

Account Destination · object

required

Destination account details

Account Destination
UMA Address Destination

Show child attributes

destination.accountId

string

required

Destination account identifier

Example:

"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

destination.currency

string

Currency code for the destination account

Example:

"EUR"

sendingCurrency

object

required

Currency for the sending amount

Show child attributes

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

Example:

"USD"

sendingCurrency.name

string

Full name of the currency

Example:

"United States Dollar"

sendingCurrency.symbol

string

Symbol of the currency

Example:

"$"

sendingCurrency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

receivingCurrency

object

required

Currency for the receiving amount

Show child attributes

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

Example:

"USD"

receivingCurrency.name

string

Full name of the currency

Example:

"United States Dollar"

receivingCurrency.symbol

string

Symbol of the currency

Example:

"$"

receivingCurrency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

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

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

paymentInstructions.accountOrWalletInfo

CLABE Account · object

required

CLABE Account
US Bank Account
PIX Account
IBAN Account
FBO Account
UPI Account
Spark Wallet
Lightning Invoice
Solana Wallet
Tron Wallet
Polygon Wallet
Base Wallet

Show child attributes

paymentInstructions.accountOrWalletInfo.accountType

enum<string>

required

Type of account or wallet information

Available options:

CLABE

Example:

"CLABE"

paymentInstructions.accountOrWalletInfo.clabeNumber

string

required

18-digit CLABE number (Mexican banking standard)

Required string length: 18

Example:

"123456789012345678"

paymentInstructions.accountOrWalletInfo.reference

string

required

Unique reference code that must be included with the payment to properly credit it

Example:

"UMA-Q12345-REF"

paymentInstructions.instructionsNotes

string

Additional human-readable instructions for making the payment

Example:

"Please ensure the reference code is included in the payment memo/description field"

Example:

[
  {
    "accountType": "US_ACCOUNT",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "bankName": "Chase Bank",
    "referenceCode": "REF123456"
  },
  {
    "accountType": "SPARK_WALLET",
    "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
  }
]

originalQuoteId

string

ID of the quote that is being retried

Example:

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

rateDetails

object

Details about the rate and fees for the transaction.

Show child attributes

rateDetails.counterpartyMultiplier

number<double>

required

The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution.

Example:

1.08

rateDetails.counterpartyFixedFee

integer<int64>

required

The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents).

Required range: x >= 0

Example:

10

rateDetails.gridApiMultiplier

number<double>

required

The underlying multiplier from the sending currency to mSATS, including variable fees.

Example:

0.925

rateDetails.gridApiFixedFee

integer<int64>

required

The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents).

Required range: x >= 0

Example:

10

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

Example:

0.003

rateDetails.gridApiVariableFeeAmount

number<int64>

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.

Required range: x >= 0

Example:

30

Create a transfer quote Execute a quote

⌘I

Using the API

API documentation

Retry an incomplete payment

Authorizations

Path Parameters

Body

Response