Listing Transactions

Query card transactions with filters and pagination

GET /cards/{id}/transactions returns the parent CardTransaction rows for a card, with all of the pulls, clearings, and refunds rolled up into aggregate summaries.

The basic shape

curl -X GET "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010/transactions?limit=20" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

A single row looks like:

{
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "issuerTransactionToken": "lithic_txn_b81c2a4f",
  "status": "SETTLED",
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  },
  "authorizedAmount":  { "amount": 1250, "currency": { "code": "USD" } },
  "settledAmount":     { "amount": 1500, "currency": { "code": "USD" } },
  "refundedAmount":    { "amount":    0, "currency": { "code": "USD" } },
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "pullSummary":       { "count": 2, "totalAmount": 1500, "pendingCount": 0 },
  "refundSummary":     { "count": 0, "totalAmount":    0 },
  "settlementSummary": { "count": 1, "totalAmount": 1500 },
  "authorizedAt": "2026-05-08T14:30:00Z",
  "lastEventAt":  "2026-05-08T15:42:11Z",
  "createdAt":    "2026-05-08T14:30:00Z",
  "updatedAt":    "2026-05-08T15:42:11Z"
}

pullSummary.count = 2 with settledAmount > authorizedAmount is the restaurant-tip / over-auth path: the original auth pulled $12.50, and a post-hoc pull added$2.50 when the merchant cleared for $15.00.

Available filters

Parameter	Notes
status	AUTHORIZED | PARTIALLY_SETTLED | SETTLED | REFUNDED | EXCEPTION
merchantDescriptor	Substring match on the captured descriptor string
mcc	Four-digit ISO 18245 code, exact match
startDate, endDate	ISO 8601 timestamps, inclusive, applied to createdAt
limit	1–100, default 20
cursor	Returned from the previous page
sortOrder	asc or desc, default desc

The EXCEPTION view

Rows with status: "EXCEPTION" are where the transaction settled to the card network but the corresponding pull from the funding source failed. These are the high-urgency reconciliation alerts — every on-call dashboard should expose this query:

curl -X GET "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010/transactions?status=EXCEPTION" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

See Reconciliation for what drives an exception and how to act on it.

Going deeper than the parent

The aggregates on the parent (pullSummary, settlementSummary, refundSummary) are typically all you need for reconciliation. When you need per-child detail, fetch the parent and follow the issuerTransactionToken into the issuer’s records, or use GET /cards/{id}/transactions/{transactionId} (out of scope of this list endpoint) for the per-event breakdown.