Model finality in Formance Ledger
Pick the rail in your stack with the longest reversal window, run the open-source Formance Ledger locally, and post your first finality-aware transaction.
A $20,000 payment lands in a merchant's account at 10:00 AM. The dashboard says "paid," and the confirmation email has gone out. Depending on which rail carried that money, the merchant might be safe to ship immediately, or exposed to a clawback for the next 120 days. The scenario of when money is confirmed as paid, and when it actually executes, is referred to as transaction finality.
Every payment system draws its own line between "in flight" and "done," and those lines rarely match up. Card networks operate on batch cycles that can stretch settlement over days and leave the door open to chargebacks for weeks. ACH transfers can be pulled back after the fact. Even SEPA payments, though fast, depend on bank participation before the funds are considered secure.
For decades, the legal-agreement model worked. Finality was slow, but predictable. Now, the collision of instant payment systems, digital assets, and multi-rail orchestration makes the question "When is money really there?" a more common, and more complicated, one.
Finality is a core requirement for any system that moves money. Product teams must reconcile a user's perception of finality with the moment a transfer becomes irreversible. Designing with finality in mind means modeling and recording each state transition, from initiation through clearing, settlement, and completion, so the flow of value stays transparent and verifiable.
Transaction finality is the point at which a payment becomes irrevocable, when no mechanism, whether legal, procedural, or technical, can reverse the transfer. Before that point, a payment is provisional. After it, the value has changed hands.
Finality is closely related to, but distinct from, settlement. Settlement is the actual transfer of value between accounts. Finality is the moment that transfer becomes irreversible. Depending on the rail, finality can arrive before settlement, at the same time, or long after.
However, "irrevocable" means different things on different rails. A Fedwire credit is effectively locked the moment the receiving bank accepts it. A card payment can look identical on the merchant's dashboard yet remain reversible for months through chargebacks.
Three reversal mechanisms often get conflated with transaction finality and are worth separating:
Rulebooks, contracts, and regulations governing each rail define when a transaction is safe to treat as irrevocable.
In traditional finance, transaction finality is a legal construct enforced by clearinghouses, counterparties, and regulators, not by code, like blockchains and algorithms.
In systems like ACH, SEPA, and card networks, a payment is "final" only once those parties agree it cannot be reversed. Contracts and regulations create that agreement. The U.S. Uniform Commercial Code, the EU Settlement Finality Directive, and central bank policies define when obligations are settled and which entities bear residual risk.
Finality timing varies widely across payment rails, from seconds on Fedwire to months on a consumer card dispute, shaped by the rulebooks, settlement cycles, and reversal rights that govern each one.
The table below summarizes each rail's settlement timing, reversal/return window, and the ledger state a well-designed system should assign.
| Rail | Settlement timing | Reversal/return window | Ledger state at settlement |
| ACH (consumer debit) | Deferred net settlement (batch) | Extended return period for unauthorized debits | settled_disputable |
| ACH (corporate debit) | Deferred net settlement (batch) | Shorter return period under applicable rules | settled_disputable |
| Fedwire | Real-time gross settlement | Generally no unilateral return; a return requires the recipient's cooperation | final |
| RTP / FedNow | Real-time gross settlement | Return requests generally require cooperation rather than a unilateral clawback | final |
| SEPA Instant (SCT Inst) | Real-time gross settlement | Limited recall grounds and separate protections may apply | final |
| SWIFT (cross-border wire) | Multi-hop via correspondent banks; hours to days | Recall requires cooperation of every correspondent in the chain | settled_at_risk |
| Cards (Visa / Mastercard) | Deferred net settlement (batch) | Extended dispute and chargeback periods | settled_at_risk |
The ledger states shown here are the account naming conventions to model each rail's finality profile, and they reappear as account names in the Numscript examples later on.
Traditional finality, in other words, is an institutional trust. It's slow-moving, human-mediated, and legally enforced.
Blockchains introduced a new model of finality based on mathematical consensus instead of a legal agreement. Once a transaction is embedded in a blockchain, undoing it becomes increasingly improbable as the chain progresses. With no clearinghouse or central bank making the finality decision, consensus rules and economic incentives decide when history is fixed.
The shift moves the question from "who enforces the rules?" to "what guarantees the rules can't be changed?" Blockchain consensus produces three distinct forms of finality, each with different guarantees.
Probabilistic finality means a transaction becomes progressively harder, but never impossible, to reverse. Every additional Bitcoin block makes a confirmed transaction more difficult to unwind, although the reversal probability never becomes literally zero.
High-value transfers commonly wait for multiple confirmations. The user chooses the required level of confidence because the protocol never announces an absolute closing point.
Deterministic finality means a transaction is final once the protocol formally seals it, making reversal economically prohibitive. Ethereum, for example, finalizes checkpoints after the protocol's required sequence of epochs.
However, reversing a finalized checkpoint would require severe protocol penalties against a substantial portion of validators, making reversal achievable but economically devastating.
Instant, or Byzantine Fault Tolerant (BFT), finality means a block is final the moment a validator supermajority signs it, with no waiting period.
BFT chains require agreement before adding a block to the chain. Solana reaches its finalized commitment after the required voting process, while planned consensus upgrades aim to reduce that delay.
Avalanche and Tendermint-based Cosmos chains are also designed for rapid finalization. BFT finality most closely approximates instant on-chain finality: validator agreement produces a deterministic outcome without requiring users to count confirmations.
As a result, crypto transaction finality exists in a dual world where legal systems and consensus systems overlap, but don't always align.
Instant payment confirmations often mask settlement processes that are still in flight. Real-time payment networks such as the FedNow payment service (U.S.), SEPA Instant (EU), and UPI (India) have changed what users expect from a payment experience.
For most people, a completed confirmation implies that settlement has already happened. Institutions, however, may still be settling through slower back-end rails behind that apparently "instant" result.
Behind the scenes, many banks still rely on legacy payment rails such as ACH or SWIFT for actual settlement. A payment may appear final to the sender, while the underlying transfer remains pending or conditional.
The mismatch between perception and reality costs real money. A retailer that ships a product the moment a card processor returns a "payment successful" message has already released the inventory. If a dispute or chargeback is filed later, the retailer must absorb the reversal on its own balance sheet.
The same happens in marketplaces that credit a seller’s wallet before funds have cleared the acquiring bank. Instant payment rails shorten the lag between authorization and settlement, but they do not remove it. When you ignore that transaction finality gap, liquidity exposure and fraud loss become serious risks.
Two problems make the finality continuum hard to manage: legal finality doesn't match protocol finality, and multi-rail payments landscapes impact each other.
Finality isn't binary because a single transaction progresses through initiation, clearing, settlement, and eventual irreversibility, and each rail draws its "done" line at a different point in that sequence.
Protocol finality is the consensus point after which reversing a transaction becomes computationally infeasible, while legal finality is when a court or regulator treats the transfer as irreversible, even in insolvency.
A blockchain can guarantee the first but cannot guarantee the second on its own. The Bank for International Settlements’s Principles for Financial Market Infrastructures establish that settlement must be clear, certain, and legally enforceable even in the event of insolvency.
Aligning the two requires governance that translates protocol assurance into enforceable legal settlement, a task at the intersection of technology, policy, and market design.
When a payment traverses different rails, such as a card charge funding a blockchain-based wallet, each system applies its own definition of completion. A refund or reversal on one rail can invalidate a transaction that appeared final on another.
Stablecoins are the clearest example. Although they use blockchain rails, their promise of fiat redemption depends on legal and custodial arrangements. A token can settle immediately on-chain while the underlying monetary claim remains subject to conventional legal finality, especially across borders. Regulatory initiatives like the U.S. GENIUS Act and MiCA in the EU are working to close that divide.
Neither problem can be solved in the protocol alone. Both live in the ledger: in how it models states, gates credits, and reconciles across rails.
Six steps put transaction finality into practice and turn abstract finality rules into concrete ledger design. Map rails, model states, gate credits, log transitions, reconcile, and compensate.
Each step ties reversal periods and consensus requirements to explicit transaction states, so financial products can identify when a transaction becomes permanent and maintain a single source of financial truth across every rail they touch.
Before you build anything, list every rail your product touches and write down the longest period a settled transfer can still be pulled back. That number is what the rest of the ledger has to defend against.
The range is wider than most teams assume. A Fedwire credit is effectively locked the moment the receiving bank accepts it. A consumer card payment can look settled the same day but remain reversible for months through chargebacks. A Bitcoin deposit isn't safe until it's cleared enough confirmations, and an Ethereum transfer isn't safe until its checkpoint has finalized. Stablecoin transfers settle on-chain in seconds but carry the issuer's custodial and legal risk.
For each rail, record three things:
You can't design the rest of the ledger until this map exists.
A production core ledger should distinguish pending, posted, settled, reversed, refunded, returned, and disputed transactions. It should also keep posted, available, reserved, and withdrawable balances separate. Combining these states conceals risk.
Every rail needs its own settled-but-not-yet-final state, like below:
Explicit states make reversal exposure visible in the ledger.
Don't make funds spendable until the rail carrying them has reached its true final state.
"Settled" on a bank file, a processor dashboard, or a block explorer is not the same as irrevocable. If the rail still allows a reversal, or if the chain hasn't reached the finality threshold you've committed to, the ledger should still be holding the money in a reserved state.
Marketplaces end up chasing sellers for clawbacks, retailers ship inventory against payments that later disappear, and crypto exchanges credit a deposit that gets orphaned when the chain reorganizes when finality isn't established.
The reversal or confirmation window from Step 1 tells you exactly how long the reserved state has to last. Only after that window closes does the balance become available to spend.
Use explicit events to initiate state changes instead of inferring them from logs, and retain processor responses verbatim.
Each transition from pending through settled to final should create a timestamped record that identifies its source and authorizing rule, whether that source is an ACH return file, a card network webhook, or an on-chain finalization event.
Idempotency is a non-negotiable requirement. Replaying a webhook or reprocessing a block cannot advance the same transaction twice. Immutability and bi-temporality matter here, since bi-temporality records both when an event took effect and when the system recorded it.
An ACH return received after settlement, or a chain reorganization that invalidates a previously seen block, can therefore enter the correct period while the ledger preserves a complete audit trail.
In Numscript, Formance's purpose-built language for describing financial transactions, a card charge that hasn't cleared its chargeback window can be routed straight into an at-risk holding account:
In Numscript, Formance's purpose-built language for describing financial transactions, a card charge that hasn't cleared its chargeback window can be routed straight into an at-risk holding account. The example below posts $20,000.00 into @merchant:settled_at_risk; a second, separately triggered posting moves the funds to @merchant:final only after the dispute window closes:
send [USD/2 2000000] (
source = @world
destination = @merchant:settled_at_risk
)
Once the dispute window closes, a second, separately triggered posting moves the funds to @merchant:final. The same pattern applies to a Bitcoin deposit moving from pending_confirmations to final once it clears the required block depth. The ledger holds both events, so the state transition is auditable.
Treat the core ledger as the system of record and compare it continuously with the corresponding source of truth for each rail, including bank files for ACH and wires, PSP reports for cards, block explorer or node data for on-chain transfers, and issuer attestations for stablecoins.
Ongoing reconciliation exposes differences between operational movement and final settlement before customers experience them. It is also the dependable way to detect a reversal, a chain reorganization, or a stablecoin depeg event that arrives through a rail no team is actively monitoring.
Multi-rail transactions need explicit compensation logic because they cannot be atomic. A business transaction that crosses two rails, such as a card charge used to fund a stablecoin payout or a Bitcoin deposit used to trigger a fiat payment, does not automatically gain atomicity.
One side may become final while the other remains reversible. Durable, event-driven orchestration should either commit both legs or create an explicit compensating ledger entry. No transaction should remain partially committed between fiat and digital-asset rails.
Finality is a series of state transitions, each governed by a different rulebook, protocol, or piece of law. Teams that move money reliably model those transitions explicitly, reconcile them continuously, and never confuse "settled" with "final."
Treat payments as evolving states, so every transition from initiation to clearing to settlement triggers explicit updates in the ledger and event streams. Model finality correctly, and every decision (crediting a wallet, releasing goods, or triggering a payout) rests on a stable foundation.
Pick the rail in your stack with the longest reversal window and model its pending → settled_at_risk → final sequence end to end.