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

A refused authorization opens the transaction directly in DECLINED — it never passes through AUTHORIZED. A merchant RETURN does not move the status. The transaction stays SETTLED and the returned value appears in refundedAmount. 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,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 DECLINED path

A transaction lands in DECLINED when the auth is refused outright, or 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: "DECLINED" for a card-destination transaction. The payload includes the full parent record, so your dashboard’s decline view is driven entirely by webhook deliveries — there’s no list endpoint to poll. A failed pull doesn’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 it 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.