Simulate sending funds

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/send \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "currencyCode": "USD",
  "currencyAmount": 1000
}
'

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "status": "CREATED",
  "type": "INCOMING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "sentAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "paymentInstructions": [
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "referenceCode": "REF123456"
    },
    {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  ],
  "settledAt": "2025-08-15T14:30:00Z",
  "createdAt": "2025-08-15T14:25:18Z",
  "updatedAt": "2025-08-15T14:30:00Z",
  "description": "Payment for invoice #1234",
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "exchangeRate": 1.08,
  "fees": 10,
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "originalTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000003",
  "refund": {
    "reference": "UMA-Q12345-REFUND",
    "initiatedAt": "2025-08-15T14:30:00Z",
    "settledAt": "2025-08-15T14:30:00Z"
  },
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  },
  "failureReason": "QUOTE_EXPIRED"
}

POST

sandbox

send

Simulate sending funds

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/send \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "currencyCode": "USD",
  "currencyAmount": 1000
}
'

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "status": "CREATED",
  "type": "INCOMING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "sentAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "paymentInstructions": [
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "referenceCode": "REF123456"
    },
    {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  ],
  "settledAt": "2025-08-15T14:30:00Z",
  "createdAt": "2025-08-15T14:25:18Z",
  "updatedAt": "2025-08-15T14:30:00Z",
  "description": "Payment for invoice #1234",
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "exchangeRate": 1.08,
  "fees": 10,
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "originalTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000003",
  "refund": {
    "reference": "UMA-Q12345-REFUND",
    "initiatedAt": "2025-08-15T14:30:00Z",
    "settledAt": "2025-08-15T14:30:00Z"
  },
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  },
  "failureReason": "QUOTE_EXPIRED"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

quoteId

string

required

The unique identifier of the quote

Example:

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

currencyCode

string

required

Currency code for the funds to be sent

Example:

"USD"

currencyAmount

integer<int64>

The amount to send in the smallest unit of the currency (eg. cents). If not provided, the amount will be derived from the quote.

Example:

1000

Response

Funds received successfully

string

required

Unique identifier for the transaction

Example:

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

status

enum<string>

required

Status of a payment transaction

Available options:

CREATED,

PENDING,

PROCESSING,

COMPLETED,

REJECTED,

FAILED,

REFUNDED,

EXPIRED

type

enum<string>

required

Type of transaction (incoming payment or outgoing payment)

Available options:

INCOMING,

OUTGOING

source

Account Source · object

required

Source account details

Account Source
UMA Address Source

Show child attributes

source.accountId

string

required

Source account identifier

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

source.currency

string

required

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

required

Currency code for the destination account

Example:

"EUR"

customerId

string

required

System ID of the customer (sender for outgoing, recipient for incoming)

Example:

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

platformCustomerId

string

required

Platform-specific ID of the customer (sender for outgoing, recipient for incoming)

Example:

"18d3e5f7b4a9c2"

sentAmount

object

required

Amount sent in the sender's currency

Show child attributes

sentAmount.amount

integer<int64>

required

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example:

12550

sentAmount.currency

object

required

Show child attributes

sentAmount.currency.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"

sentAmount.currency.name

string

Full name of the currency

Example:

"United States Dollar"

sentAmount.currency.symbol

string

Symbol of the currency

Example:

"$"

sentAmount.currency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

paymentInstructions

object[]

required

Payment instructions for executing the payment.

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

settledAt

string<date-time>

When the payment was or will be settled

Example:

"2025-08-15T14:30:00Z"

createdAt

string<date-time>

When the transaction was created

Example:

"2025-08-15T14:25:18Z"

updatedAt

string<date-time>

When the transaction was last updated

Example:

"2025-08-15T14:30:00Z"

description

string

Optional memo or description for the payment

Example:

"Payment for invoice #1234"

counterpartyInformation

object

Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.

Example:

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

receivedAmount

object

Amount to be received by recipient in the recipient's currency

Show child attributes

receivedAmount.amount

integer<int64>

required

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example:

12550

receivedAmount.currency

object

required

Show child attributes

receivedAmount.currency.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"

receivedAmount.currency.name

string

Full name of the currency

Example:

"United States Dollar"

receivedAmount.currency.symbol

string

Symbol of the currency

Example:

"$"

receivedAmount.currency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

exchangeRate

number

Number of sending currency units per receiving currency unit.

Example:

1.08

fees

integer<int64>

The fees associated with the quote in the smallest unit of the sending currency (eg. cents).

Required range: x >= 0

Example:

10

quoteId

string

The ID of the quote that was used to trigger this payment

Example:

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

originalTransactionId

string

ID of the original transaction that this transaction is retrying, if applicable

Example:

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

refund

object

The refund if transaction was refunded.

Show child attributes

refund.reference

string

required

The unique reference code of the refund

Example:

"UMA-Q12345-REFUND"

refund.initiatedAt

string<date-time>

required

When the refund was initiated

Example:

"2025-08-15T14:30:00Z"

refund.settledAt

string<date-time>

When the refund was or will be settled

Example:

"2025-08-15T14:30:00Z"

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

failureReason

enum<string>

If the transaction failed, this field provides the reason for failure.

Available options:

QUOTE_EXPIRED,

QUOTE_EXECUTION_FAILED,

LIGHTNING_PAYMENT_FAILED,

FUNDING_AMOUNT_MISMATCH,

COUNTERPARTY_POST_TX_FAILED,

TIMEOUT

Cancel an UMA invitation Simulate payment send to test receiving an UMA payment

⌘I

Using the API

API documentation

Simulate sending funds

Authorizations

Body

Response