Test the payfac ledger model on GitHub
Adopting Formance Ledger on GitHub means testing a ledger that enforces the atomic settlement split, per-sub-merchant isolation, immutable posting history, and bi-temporal correction model by construction.
Becoming a payment facilitator (Payfac) puts two engineering loads on the platform the day the sponsor agreement goes live.
Call them the ledger and proof loads. The first load is a ledger, and the second is a continuous reconciliation load.
The acquirer settles one gross wire into the payfac's for-benefit-of (FBO) account, and from that moment the payfac's internal ledger is the only record of which sub-merchant owns which dollars in the FBO account.
The ledger load holds thousands of sub-merchant balances inside one omnibus account, each with fee carve-outs, rolling reserves, and its own payout schedule. The continuous reconciliation load proves, on every settlement cycle, that internal balances match bank statements, processor reports, and rail confirmations.
Both loads land on platforms graduating from a referral or independent sales organization (ISO) arrangement into registered payment facilitator status. Registration guides price the card-network fees and the Payment Card Industry Data Security Standard (PCI DSS) Level 1 work, but none consider the ledger or the continuous reconciliation workload that persists long after registration is complete.
This guide covers the ledger and reconciliation requirements a platform inherits when it becomes a registered payment facilitator. From atomic settlement splits and sub-merchant isolation through to bi-temporal corrections, continuous reconciliation, and the five invariants a sponsor bank expects on demand.
A payfac ledger must enforce double-entry integrity, per-sub-merchant isolation, immutability, bi-temporal tracking, and real-time state tracking across three physical bank accounts: the FBO account, the operating account, and the reserve account.
In an FBO model, funds flow from card networks to the acquirer, into the payfac omnibus account, and out to sub-merchants on the payfac's schedule. Under card-brand rules, payment facilitators with the relevant state and federal licenses may receive sub-merchant settlement funds.
Controlling sub-merchant funding in-house can trigger money transmission obligations, which the payfac must resolve with the sponsor bank and counsel before launch.
A payfac double-entry engine must post debits equal to credits on every entry. It must also decompose every gross settlement into balanced postings across interchange, scheme fees, processor markup, payfac fee revenue, reserve holds, and net sub-merchant payable.
Formance is an open-source, programmable core ledger that unifies fiat and digital assets with regulatory-grade traceability, and Formance enforces atomic, balanced-by-construction postings so a settlement split either commits in full or does not commit at all.
Sub-merchant isolation requires separate virtual wallets for every sub-merchant inside the omnibus account. It aggregates the FBO balance and decomposes it into a per-merchant subledger that sums to the FBO total.
The invariant is: omnibus bank balance = Σ sub-merchant ledger balances. It is provable at any moment. Auditors, sponsor banks, and partner acquirers see only the aggregate FBO balance, so the payfac's internal ledger makes the aggregate decomposable per sub-merchant.
Immutable posting logs prohibit editing or deletion of any written record, so corrections post as new balancing postings against the affected sub-merchant's account. It never uses in-place edits or a generic suspense account.
A suspense correction destroys per-sub-merchant balance accuracy at the moment an auditor or sponsor bank requests the balance.
Immutability produces regulatory-grade traceability. Every balance is the sum of the immutable posting history, and any auditor or sponsor-bank reviewer can replay the history to reconstruct any balance at any date.
Bi-temporal adjustment tracking requires every correction to reference the original posting and carry two timestamps: the effective date of the underlying event and the recorded date in the payfac system.
Acquirers reissue settlement files days after the original file lands. Without bi-temporal settlement timing, the amended file forces the payfac operator to choose between rewriting history and losing the correction.
With bi-temporality, the amended file lands as a dated correction, and the payfac ledger can still answer what the sub-merchant balance was on the original settlement date.
Real-time state tracking means funds move through authorized, captured, settled, and holding states, so each reserve tranche (a single part, segment, or portion of a larger financial pool) carries its settlement date for downstream release scheduling.
Three posting shapes cover the reserve lifecycle:
Each reserve tranche ages from its own settlement date, so release scheduling comes from the payfac ledger. Rolling reserve percentages and hold windows vary by merchant risk band and are set by the payfac's underwriting policy.
A payfac operates three physical bank accounts, and the ledger's account topology maps cleanly onto them so every posting corresponds to a real bank movement.
The FBO account holds sub-merchant funds, the operating account holds payfac fee revenue and expenses, and the reserve account holds rolling reserves against chargeback exposure.
If the ledger points sub-merchant funds to the wrong bank account, that money gets mixed with the payfac's own fee revenue, creating a money-transmission licensing risk and making per-merchant reconciliation impossible.
Numscript, Formance’s open-source language for financial transactions, encodes the daily settlement split as a single atomic transaction across the three physical accounts.
A $2,400,000 gross acquirer wire decomposes into interchange, scheme fees, processor markup, payfac fee revenue, a rolling reserve hold, and the net sub-merchant payable.
The @counterparties:psps:provider:settlement account is the named PSP settlement boundary.
The @platform:fees:* and @platform:revenue:fees accounts hold platform-owned allocations bound for the operating account. The @merchants:8804:reserve:rolling and @merchants:8804:payable accounts (where 8804 is a placeholder sub-merchant ID) hold the reserve and FBO balances.
Amounts use USD/2 (cents), so 240000000 represents $2,400,000:
// DAILY_SETTLEMENT_SPLIT
// Event: split a $2,400,000 provider settlement into fees, revenue, reserve, and merchant payable
send [USD/2 240000000] (
source = @counterparties:psps:provider:settlement allowing unbounded overdraft
destination = {
max [USD/2 3840000] to @platform:fees:interchange
max [USD/2 1200000] to @platform:fees:scheme
max [USD/2 960000] to @platform:fees:processor:markup
max [USD/2 4800000] to @platform:revenue:fees
max [USD/2 12000000] to @merchants:8804:reserve:rolling
remaining to @merchants:8804:payable
}
)
set_tx_meta("event_type", "daily_settlement_split")
set_tx_meta("settlement_id", "stl001")
Either all six legs commit, or none do. The account paths mirror the money movement architecture described by the payfac's daily bank and processor statements.
Bank rails and payment-provider APIs execute the physical transfers. The ledger records the resulting bank-account balances and does not hold or move funds.
Payfac reconciliation must sustain continuous three-way matching, multi-format settlement file ingestion, per-sub-merchant payout accuracy, first-class settlement timing states, idempotent payout retries, and automated chargeback clawbacks.
Payfac reconciliation runs the omnibus invariant continuously, across every settlement cycle, every card brand, and every disbursement rail.
Three-way match runs automated checks across gateway and processor reports, FBO bank statements, and internal ledger postings, proven on every cycle rather than sampled.
Automated invariant checks should run against the same core ledger that holds the postings. Reconciliation checks aggregate financial state against external statements at configured intervals.
Data drift between the payfac ledger and acquirer statements surfaces at the configured intervals rather than at a monthly close.
Formance Reconciliation matches aggregate state, not individual ledger postings, to each bank or PSP statement line. The ledger handles the line-level postings.
Payfac reconciliation requires an ingestion layer that parses bank- and processor-specific formats, including BAI2, CAMT.053, CAMT.054, ISO 20022 messages. It also requires card-brand raw settlement files to be turned into postings that the ledger can match.
Settlement file schemas vary by provider, so normalization is a schema-mapping problem the payfac must solve before reconciliation begins.
A sub-merchant payable equals gross sales minus interchange, scheme fees, processor markup, payfac fees, refunds, and chargebacks. Every deduction has its own posting, so the payout amount is a single query against the ledger.
When deductions aren't posted individually, every sub-merchant dispute about a payout figure becomes a manual CSV reconstruction rather than a single ledger lookup.
Payfac reconciliation models different settlement speeds across card brands and disbursement rails. Authorization on D+0 and settlement on D+2 or later both exist as first-class ledger states, and payouts are only for settled funds.
Reconciliation classifies three drift causes separately.
Genuine mismatches and fee disclosure gaps get a compensating posting on the affected sub-merchant's account so per-merchant balances stay accurate through the correction.
Variance resolution auto-flags sub-cent variance from fee disclosure gaps or rounding and posts a compensating entry.
The higher-cost failure mode in payout processing is duplicate payout: a payout retry fires twice against a disbursement rail without idempotency scoped to the payfac's internal operation record.
The payfac-specific duplicate-payout trigger is a 5xx response from the disbursement rail after the acquirer has already processed the payout. The acquirer has processed the payout, but the payfac is unaware. A retry keyed to the acquirer's transaction ID can diverge from the payfac's internal operation record and post a duplicate to the sub-merchant's balance.
The mitigation is three-part. Write a durable operation record before any external call. Scope the idempotency key to the internal operation record. Add a reconciliation step that queries the disbursement rail for the operation's terminal state before any retry posts to a sub-merchant balance.
Chargeback clawback automation from tranche-dated reserves
Chargeback clawback automation freezes the disputed amount at the sub-merchant payable account upon dispute notification and draws down from the reserve tranche dated to the original settlement.
Reserve aging turns clawback from a treasury funding decision by finance ops into a posting rule the ledger executes automatically.
The payfac's ledger and reconciliation stack must demonstrate five invariants on demand before signing a sponsor agreement:
Any stack that cannot demonstrate the five invariants on demand fails sponsor-bank sign-off regardless of engineering headcount or timeline allocation.