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, including what a reversal and an expiry do to the status.

​
The event model

For each card authorization, Grid produces:
  1. One CardTransaction per purchase — 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. A return against a known purchase opens its own dated CardTransaction row (direction: CREDIT) linked to the purchase via originalTransactionId, so statements can list it as its own line.
Clearings are reconciled against the purchase and rolled up into its settledAmount total; the returned value lives on the refund row.

​
Status transitions

The status is not stored. Grid re-derives it from the events recorded so far every time you read the transaction, so a status can change in either direction as later events arrive. DECLINED is the one exception: nothing was pulled, and no further event follows. A merchant RETURN does not move the purchase’s status. The purchase stays SETTLED; the return posts as its own CREDIT transaction. A partial authorization reversal releases part of the hold and lowers authorizedAmount. The transaction stays AUTHORIZED. A full reversal or an expiry releases the whole hold, which leaves nothing outstanding, so the transaction resolves as SETTLED with a settledAmount of zero. Every transition is delivered as a CARD_TRANSACTION.* webhook whose data is the whole post-change CardTransaction — see Webhooks.

​
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 settledAmount: 1500.
The post-settlement parent carries authorizedAmount: 1250 and settledAmount: 1500.

​
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 transaction webhook with status: "EXCEPTION" for a card-destination transaction. 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 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.