Reconciliation

How card transactions reconcile, and what exceptions to act on

A card transaction is not a single event — it’s a parent row plus a stream of child events from the card network. This page covers the event model, the status transitions, and how to handle the EXCEPTION path.

The event model

For each card authorization, Grid produces:

1. One parent CardTransaction — created at auth time, persists for the life of the transaction.
2. Pulls — debits against the funding source that fund approved auths and any post-hoc settlements.
3. Clearings — the network’s confirmation that funds have moved.
4. Refunds — merchant-initiated RETURN events.

Children are reconciled against the parent and rolled up into three aggregates: pullSummary, settlementSummary, and refundSummary. You don’t see per-child rows on the list endpoint — they’re summarized on the parent.

Status transitions

              ┌─────────────────────────────────────┐
              │                                     ▼
AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED ──► REFUNDED
              │
              └──► EXCEPTION  (pull failed after settlement)

Status	Meaning
AUTHORIZED	Auth approved, hold placed, no clearings yet.
PARTIALLY_SETTLED	At least one clearing landed, but more are still expected (split shipments, multi-leg trips).
SETTLED	All clearings for the auth have posted. The transaction is closed against the funding source.
REFUNDED	A RETURN was received and the net settled amount has been refunded in full or part.
EXCEPTION	The transaction settled to the network but the corresponding pull from the funding source failed.

Every transition emits a CARD_TRANSACTION.UPDATED webhook with the post-change parent.

The over-auth path

The most common non-trivial flow is the over-auth (e.g. restaurant tip). The auth comes in at $12.50, but the merchant clears for$15.00.

1. Auth approved → one pull for $12.50 → parent is AUTHORIZED.
2. Clearing for $15.00 → second post-hoc pull for$2.50 → parent is SETTLED with pullSummary.count = 2, settlementSummary.totalAmount = 1500.

This is what Listing transactions shows in the example response: authorizedAmount: 1250, settledAmount: 1500, two pulls.

The EXCEPTION path

An exception happens when the card network has already moved funds for a settlement but Grid can’t pull the matching amount from the funding source — typically because the cardholder’s balance no longer covers the post-hoc difference.

Signals to watch:

• A CARD_TRANSACTION.UPDATED webhook with status: "EXCEPTION".
• pullSummary.pendingCount > 0 that fails to drop to zero in the expected settlement window.

The on-call dashboard query is just:

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

Exceptions don’t roll back automatically. The standard response is to top up the funding source (or move the customer to a state where their balance can be collected) and contact Lightspark support to drive the exception to resolution.

Idempotency on webhooks

Every CARD_TRANSACTION.UPDATED webhook carries a unique id. Track processed webhook IDs and treat duplicates as no-ops — Grid retries failed deliveries, and your reconciliation should be safe under at-least-once delivery.

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000040",
  "type": "CARD_TRANSACTION.UPDATED",
  "timestamp": "2026-05-08T14:30:00Z",
  "data": { /* full CardTransaction */ }
}

See Webhooks for signature verification and the full payload shape.