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 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

AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED
    │
    ├──► DECLINED   (auth declined, no money moved)
    └──► EXCEPTION  (pull failed after settlement)

A merchant RETURN does not move the purchase’s status. The purchase stays SETTLED; the return posts as its own CREDIT transaction.

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. A RETURN received afterwards keeps it SETTLED; the return appears as its own CREDIT transaction.
DECLINED	The authorization was declined before any money moved. Declines must be excluded from cardholder statements.
EXCEPTION	The transaction settled to the network but the corresponding pull from the funding source failed.

Every transition is delivered as a CARD_TRANSACTION.* webhook carrying the post-change parent — 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, 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 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.