List Transactions

Retrieve transaction history with flexible filtering options. Transactions are returned in descending order (most recent first) with a default limit of 20 per page.

cURL

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

{
  "data": [
    {
      "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
      "status": "COMPLETED",
      "type": "OUTGOING",
      "source": {
        "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "currency": "USD"
      },
      "destination": {
        "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
        "currency": "EUR"
      },
      "sentAmount": {
        "amount": 10000,
        "currency": {
          "code": "USD",
          "symbol": "$",
          "decimals": 2
        }
      },
      "receivedAmount": {
        "amount": 9200,
        "currency": {
          "code": "EUR",
          "symbol": "€",
          "decimals": 2
        }
      },
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "platformCustomerId": "customer_12345",
      "description": "Payment for services - Invoice #1234",
      "exchangeRate": 0.92,
      "settledAt": "2025-10-03T15:30:00Z",
      "createdAt": "2025-10-03T15:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6IlRyYW5zYWN0aW9uOjAxOTU0MmY1LWIzZTctMWQwMi0wMDAwLTAwMDAwMDAwMDAzMCJ9",
  "totalCount": 45
}

Filtering transactions

Use query parameters to filter and narrow down transaction results.

Filter by customer

Get all transactions for a specific customer:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Or use your platform’s customer ID:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=customer_12345' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Filter by transaction type

Get only incoming or outgoing transactions:

Outgoing Only
Incoming Only

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=OUTGOING' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Filter by status

Get transactions in a specific status:

# Get all pending transactions
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=PENDING' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Get all completed transactions
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=COMPLETED' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Available statuses:

PENDING - Transaction initiated, awaiting processing
PROCESSING - Transaction in progress
COMPLETED - Transaction successfully completed
FAILED - Transaction failed
REJECTED - Transaction rejected

Filter by date range

Get transactions within a specific date range:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Dates must be in ISO 8601 format (e.g., 2025-10-03T15:00:00Z).

Filter by account

Get transactions for a specific account:

# Any transactions involving this account (sent or received)
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?accountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Only transactions sent FROM this account
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?senderAccountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Only transactions sent TO this account
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?receiverAccountIdentifier=ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Combining filters

You can combine multiple filters to narrow down results:

# Get completed outgoing transactions for a customer in October 2025
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&type=OUTGOING&status=COMPLETED&startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Pagination

Handle large result sets with cursor-based pagination:

Get first page

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Response:

{
  "data": [
    /* 20 transactions */
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6IlRyYW5z...",
  "totalCount": 150
}

Get next page

Use the nextCursor from the previous response:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20&cursor=eyJpZCI6IlRyYW5z...' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Continue until done

Keep paginating while hasMore is true:

async function getAllTransactions() {
  const allTransactions = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const url = cursor
      ? `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100&cursor=${cursor}`
      : `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100`;

    const response = await fetch(url, {
      headers: { Authorization: `Basic ${credentials}` },
    });

    const { data, hasMore: more, nextCursor } = await response.json();

    allTransactions.push(...data);
    hasMore = more;
    cursor = nextCursor;
  }

  return allTransactions;
}

The maximum limit is 100 transactions per request. Default is 20.

Get a single transaction

Retrieve details for a specific transaction by ID:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000030' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Best practices

Use pagination for large datasets

Always implement pagination when fetching transactions to avoid timeouts and memory issues:

// Good: Paginated approach
async function fetchWithPagination(filters) {
  const transactions = [];
  let cursor = null;

  do {
    const page = await fetchTransactionPage(filters, cursor);
    transactions.push(...page.data);
    cursor = page.nextCursor;
  } while (cursor);

  return transactions;
}

// Bad: Trying to fetch everything at once
async function fetchAll() {
  const response = await fetch("/transactions?limit=10000"); // Don't do this!
  return response.json();
}

Cache results when appropriate

For data that doesn’t change frequently (like completed transactions), implement caching:

const cache = new Map();

async function getCompletedTransactions(customerId, month) {
  const cacheKey = `${customerId}-${month}`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const transactions = await fetchMonthlyTransactions(customerId, month);
  cache.set(cacheKey, transactions);

  return transactions;
}

Use specific filters to reduce result sets

Apply filters to get only the data you need:

// Good: Specific filters
const recentFailed = await fetch(
  "/transactions?status=FAILED&startDate=2025-10-01T00:00:00Z&type=OUTGOING"
);

// Bad: Fetch everything and filter in code
const all = await fetch("/transactions");
const filtered = all.data.filter(
  (tx) =>
    tx.status === "FAILED" &&
    tx.type === "OUTGOING" &&
    new Date(tx.createdAt) > new Date("2025-10-01")
);

Handle rate limits gracefully

Implement exponential backoff for rate limit errors:

async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, {
      headers: { Authorization: `Basic ${credentials}` },
    });

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get("Retry-After") || "1",
        10
      );
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response.json();
  }

  throw new Error("Max retries exceeded");
}

Next steps

Send Payments

Learn how to send payments from internal accounts

Reconciliation

Match payments with your internal accounting systems

Error Handling

Handle transaction failures and errors

Onboarding

Managing Accounts

Sending Payments

Platform Tools

Filtering transactions

Filter by customer

Filter by transaction type

Filter by status

Filter by date range

Filter by account

Combining filters

Get a single transaction

Best practices

Next steps

Send Payments

Reconciliation

Error Handling

Onboarding

Managing Accounts

Sending Payments

Platform Tools

​Filtering transactions

​Filter by customer

​Filter by transaction type

​Filter by status

​Filter by date range

​Filter by account

​Combining filters

​Pagination

​Get a single transaction

​Best practices

​Next steps

Send Payments

Reconciliation

Error Handling

Filtering transactions

Filter by customer

Filter by transaction type

Filter by status

Filter by date range

Filter by account

Combining filters

Pagination

Get a single transaction

Best practices

Next steps