Skip to main content
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

Every state transition is delivered via a CARD_TRANSACTION.* webhook whose type names the new status (CARD_TRANSACTION.AUTHORIZED, CARD_TRANSACTION.SETTLED, …) and carries the post-update parent. See Webhooks for the full payload shape. Refund linkage differs by card program. US programs link merchant refunds to the original purchase: the purchase transitions to REFUNDED and its refundedAmount/refundSummary update. EU programs receive merchant refunds from the network WITHOUT a purchase reference, so a refund arrives as a standalone CREDIT-direction card transaction (its own CARD_TRANSACTION.* lifecycle) and the original purchase keeps its final status with refundedAmount unset. Reconcile EU refunds by merchant/amount/time rather than by parent linkage.

​
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,butthemerchantclearsfor12.50, but the merchant clears for 15.00.
  1. Auth approved → one pull for $12.50 → parent is AUTHORIZED.
  2. Clearing for 15.00→secondpost−hocpullfor15.00 → second post-hoc pull for 2.50 → parent is SETTLED with pullSummary.count = 2, settlementSummary.totalAmount = 1500.
The post-settlement parent carries authorizedAmount: 1250, settledAmount: 1500, and two pulls in its pullSummary.

​
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. Signal to watch: a CARD_TRANSACTION.EXCEPTION webhook. The payload includes the full parent record, so your dashboard’s exception view is driven entirely by webhook deliveries - there’s no list endpoint to poll. 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.* 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. See Webhooks for signature verification and the full payload shape.