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'

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=INCOMING' \
  -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
EXPIRED - Quote expired before execution

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");
}