List transactions

Retrieve a paginated list of transactions with optional filtering. The transactions can be filtered by customer ID, platform customer ID, UMA address, date range, status, and transaction type.

Card transactions are included and identified by type: CARD. In Sandbox this is how you discover a CardTransaction id after simulating an authorization — list the transactions, take the card transaction’s id, and pass it as the cardTransactionId to the clearing and return simulate endpoints.

GET /transactions

List transactions

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/transactions \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "data": [
    {
      "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
      "status": "CREATED",
      "type": "INCOMING",
      "direction": "CREDIT",
      "destination": {
        "destinationType": "ACCOUNT",
        "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
        "currency": "EUR",
        "railDetails": {
          "paymentRail": "ONCHAIN",
          "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
          "network": "SOLANA"
        },
        "onChainTransaction": {
          "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
          "network": "SOLANA"
        }
      },
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "platformCustomerId": "18d3e5f7b4a9c2",
      "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
      "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
      "settledAt": "2025-08-15T14:30:00Z",
      "createdAt": "2025-08-15T14:25:18Z",
      "updatedAt": "2025-08-15T14:30:00Z",
      "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "description": "Payment for invoice #1234",
      "sentAmount": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "exchangeRate": 1.08,
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "refund": {
        "reference": "UMA-Q12345-REFUND",
        "initiatedAt": "2025-08-15T14:30:00Z",
        "status": "COMPLETED",
        "settledAt": "2025-08-15T14:35:00Z",
        "reason": "TRANSACTION_FAILED"
      },
      "counterpartyInformation": {
        "FULL_NAME": "John Sender",
        "BIRTH_DATE": "1985-06-15",
        "NATIONALITY": "DE"
      },
      "source": {
        "sourceType": "ACCOUNT",
        "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "currency": "USD",
        "railDetails": {
          "paymentRail": "ONCHAIN",
          "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
          "network": "SOLANA"
        },
        "onChainTransaction": {
          "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
          "network": "SOLANA"
        }
      },
      "receivedAmount": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "fees": 10,
      "reconciliationInstructions": {
        "reference": "UMA-Q12345-REF",
        "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
      },
      "failureReason": "LNURLP_FAILED"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

Authorizations

Authorization · string · header · required

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

Query Parameters

customerId · string

Filter by system customer ID. To filter to transactions made on behalf of the platform, specify the platform ID as the customer ID.

actingFor · string

Filter to transactions made by agents acting for this person: those whose agent was created with this actingFor.

platformCustomerId · string

Filter by platform-specific customer ID

accountIdentifier · string

Filter by account identifier (matches either sender or receiver)

senderAccountIdentifier · string

Filter by sender account identifier

receiverAccountIdentifier · string

Filter by receiver account identifier

status · enum<string>

Filter by transaction status. Applies to payment transactions only: card transactions carry a card lifecycle status (see CardTransactionStatus) and are excluded from status-filtered queries. Combining status with type=CARD is rejected with a 400. Status of a payment transaction.

Status	Description
CREATED	Initial lookup has been created
PENDING	Quote has been created
PENDING_AUTHORIZATION	Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch GET /quotes/{quoteId} using the transaction's quoteId, then authorize its scaChallenge via POST /quotes/{quoteId}/authorize.
PROCESSING	Funding has been received and payment initiated
COMPLETED	The funds are where settlement put them. A return that takes them back moves the transaction to FAILED, and the returned side's railDetails shows RETURNED. A transaction stays COMPLETED through a return only when a later step that can't be undone already used the funds
REJECTED	Receiving institution or wallet rejected payment, payment has been refunded
FAILED	The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to COMPLETED. A returned payout stays FAILED, since it has already been refunded. Each step shows on the returned side's railDetails
REFUNDED	Deprecated. A refund is reported on the transaction's refund object, and the status stays FAILED
EXPIRED	Quote has expired. Terminal

Available options: CREATED, PENDING, PENDING_AUTHORIZATION, PROCESSING, COMPLETED, REJECTED, FAILED, REFUNDED, EXPIRED

type · enum<string>

Filter by transaction type Type of transaction

Available options: INCOMING, OUTGOING, CARD

cardId · string

Filter to card transactions made on a single card. Accepts a Card: LSID or a bare UUID. Only card transactions match, so this implies type=CARD and can be combined with customerId to list one card of a multi-card cardholder.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

reference · string

Filter by reference

startDate · string<date-time>

Filter by start date (inclusive) in ISO 8601 format

endDate · string<date-time>

Filter by end date (inclusive) in ISO 8601 format

limit · integer · default: 20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

cursor · string

Cursor for pagination (returned from previous request)

sortOrder · enum<string> · default: desc

Order to sort results in

Available options: asc, desc

Response

200

application/json

Successful operation

data · (Incoming Transaction · object | Outgoing Transaction · object | Card Transaction · object)[] · required

List of transactions matching the criteria

Incoming Transaction

Outgoing Transaction

Card Transaction

Show child attributes

hasMore · boolean · required

Indicates if more results are available beyond this page

nextCursor · string

Cursor to retrieve the next page of results (only present if hasMore is true)

totalCount · integer

Total number of transactions matching the criteria (excluding pagination)