> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction Lifecycle ยท Overview
> The mental model for the transaction flow. It covers only how the core path, authorization (freeze) then settlement (posting), works under the DeCard-Managed model; endpoints, field tables and scenario-by-scenario walkthroughs are linked out to the How-to guides.
## ๐ Guide
Under the DeCard-Managed model, every movement of card funds follows the same core path: **authorization (freeze) then settlement (posting)**. Once you understand this path, you can account for any change in a user's balance and build your own reconciliation logic on top of it.
Unlike the Partner-Managed model, **authorization decisions in the DeCard-Managed model are made inside DCS**: when the cardholder pays, the system checks that user's own balance, card status and limits, and approves or declines on the spot. No authorization request is forwarded to the partner, and there is no synchronous callback requiring the partner to respond per transaction. Authorization results and balance changes are **notified** to you by webhook, and both the hold and the deduction land on that user's own balance.
## Two stages, one bridge
Each user account is ledgered per currency and described at any point in time by three figures: **available balance (`free`), frozen balance (`freeze`) and total (`total`)**. A transaction rewrites these three figures in two stages, with the **Outstanding record** acting as the bridge between them.
| Stage | Effect on balances | Notes |
| -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authorization (freeze)** | `free` moves into `freeze`, `total` unchanged | The decision is made internally; on approval the corresponding amount is frozen. **Funds are frozen but never leave the account**, no actual deduction takes place |
| **Settlement (posting)** | Releases the `freeze` and deducts the final amount from `total` | Once the merchant submits the final amount, the transaction moves **from outstanding to posted**; the funds were already frozen, so settlement draws down the frozen amount and the total โ the available balance is untouched |
The bridge is **Outstanding**: authorization creates an outstanding record that holds the frozen amount, and settlement advances it to posted and releases the freeze. Each transaction record carries `postIndicator` (`1` for posted, `0` for outstanding) to indicate its posting state; if you only have a transaction ID and are unsure which type it is, call `POST /card/v1/transaction/id/resolve` to resolve it (the response includes a `posted` boolean).
> **Invariant**: once a transaction is **fully settled, the amount frozen at authorization converges to 0** โ any excess hold (partial settlement) returns to the available balance automatically. This is what makes reconciliation closable: as long as a transaction is not yet posted and its freeze has not been released, that transaction is not settled.
## Authorization types at a glance (authType)
Authorization results are delivered by the `CARD_TRANSACTION` webhook, where `authType` states the nature of the authorization. The DeCard-Managed model uses only the following three.
| Enum value | Name | Meaning for balances |
| ---------- | ----------------- | -------------------------------------------------------------------- |
| `EXPEND` | Purchase | Freezes the corresponding amount (`free` โ / `freeze` โ) |
| `REFUND` | Refund | Credit for a return (the final credit lands in `free` at settlement) |
| `REVERSAL` | Purchase reversal | Releases the original purchase hold (`freeze` โ / `free` โ) |
> The direction of an authorization is carried by `direction` (`DEBIT` for a debit, `CREDIT` for a credit); reversing transactions (void, reversal, refund) return `originalExternalTranId` to link back to the original transaction. For the full field tables and the step-by-step sequences of the three scenario types, see [Authorizing Transactions](../how-to-use/managing-transactions/authorizing-transactions).
## One core path, several settlement shapes
In the real world, authorizations and settlements do not always match one to one: a merchant may settle for less (tip dropped), for more (tip or surcharge added), ship in several batches, or settle with no prior authorization at all. All of these are just different ways the same authorization-then-settlement path releases holds and posts amounts. What differs is **how the frozen amount is released and what amount is posted**.
| Shape | Trigger | What happens to the hold and the posting |
| ------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Standard settlement | Settled in full for the authorized amount | Releases the full hold, posts the authorized amount, closed |
| Partial settlement | Settled amount \< authorized (for example, tip dropped) | Releases the **full** hold but posts only the actual amount; the difference returns to the available balance |
| Overage settlement | Settled amount > authorized (dining or hotel with tip) | After card network and MCC rule checks, releases the original hold and posts the actual amount |
| Multiple settlement | One authorization settled in several batches (staged e-commerce shipments) | Keeps the hold until every batch has settled, then releases and posts in one go |
| Force settlement | Settled with no prior authorization (offline or in-flight scenarios) | No hold to release; posts directly against the available balance |
| Refund | A negative transaction credited back to the account (may not reference an original transaction) | Posts directly and increases the available balance |
> For the sequence diagram, field definitions and hands-on reconciliation of each shape, see [Settlement](../how-to-use/managing-transactions/settlement).
## Where balances are ledgered and where authorization is decided
This page covers only the core mental model. The detail at each end lives on its own page.
* **Balance model** (`free` / `freeze` / `total`, per-user per-asset ledgering, custody strategies): see [Account and Asset Model (Ledgering)](./ledgering-system).
* **Authorization decisions** (the checks made inside the system, webhook notification fields, sandbox simulation): see [Authorizing Transactions](../how-to-use/managing-transactions/authorizing-transactions).
* **Settlement and posting** (the five settlement shapes, statement queries, asset movement records, ID resolution): see [Settlement](../how-to-use/managing-transactions/settlement).
## Next steps
* To see how an authorization freezes funds inside the system and which webhooks you receive, read [Authorizing Transactions](../how-to-use/managing-transactions/authorizing-transactions).
* To see how funds are actually posted, how statements are issued and how to query settlement results, read [Settlement](../how-to-use/managing-transactions/settlement).
* For the full picture of available and frozen balances and of custody strategies, read [Account and Asset Model (Ledgering)](./ledgering-system).