> ## Documentation Index
> Fetch the complete documentation index at: https://ramps-09-12-at-6557-document-descriptor-length.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
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](/cards/platform-tools/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](/cards/platform-tools/webhooks) for signature
verification and the full payload shape.