Ledger accounting
Post double-entry transactions with holds and settlements.
A ledger transaction is the unit of bookkeeping in Core: a balanced pair of debit and credit entries that together describe a movement of money. Every change to balances goes through a ledger transaction — there is no way to silently bump a balance, and there is no way to lose track of where money came from or went.
This flow covers the patterns you will use most often: posting a simple two-entry transaction, holding funds before settlement, settling a hold, and reversing an entry when something goes wrong.
This page is a flow scaffold. The full version will include code snippets for each pattern, a Mermaid sequence diagram, and a reconciliation worked example.
Before you start
You will need a Core API key, two or more ledger accounts to move funds between, and an idempotency key per posting attempt.
Patterns
Post a transaction
The simplest pattern: debit one account, credit another, both in the same currency, both for the same amount. The transaction posts atomically — either both entries land or neither does.
Hold and settle
For card authorizations and any case where you commit to a future debit, post a hold first and then settle it. The hold reserves funds; the settlement converts the reservation into a permanent debit. If the hold is not settled within its window, it expires and the funds are released.
Reverse a transaction
Reversals undo a posted transaction by posting its mirror image. The original is preserved — Core's ledger is append-only — so the audit trail stays intact.
Cross-currency
When debit and credit accounts are in different currencies, the transaction must reference an FX rate.
Steps
The full step-by-step (with code) is pending. Until it is published, see the Ledger concept page and the Core ledger API reference.
Next steps
- Issuing cards — cards spend through ledger holds and settlements.
- Payout disbursement — payouts are ledger transactions plus a rail.
- Best practices — reconciliation patterns.