Transaction Lifecycle · Overview - DCS Technical Documentation

📄 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).

Transaction lifecycle: from authorization hold to posting

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.

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.

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).
Authorization decisions (the checks made inside the system, webhook notification fields, sandbox simulation): see Authorizing Transactions.
Settlement and posting (the five settlement shapes, statement queries, asset movement records, ID resolution): see Settlement.

Next steps

To see how an authorization freezes funds inside the system and which webhooks you receive, read Authorizing Transactions.
To see how funds are actually posted, how statements are issued and how to query settlement results, read Settlement.
For the full picture of available and frozen balances and of custody strategies, read Account and Asset Model (Ledgering).

​📄 Guide

​Two stages, one bridge

​Authorization types at a glance (authType)

​One core path, several settlement shapes

​Where balances are ledgered and where authorization is decided

​Next steps