Principle
Every credible wallet, treasury, or asset-operations product needs a ledger that is more authoritative than a dashboard balance.
Mozaca models balances as derived state from immutable events and double-entry journal entries. Available, pending, reserved, failed, reversed, and settled states must be explainable from the ledger.
Journal entry shape
Journal entries should reference the originating transfer, wallet, account, approval, rail event, and idempotency key so support and auditors can trace why a balance changed.
{
"id": "jrn_01J0N4RK7H",
"transferId": "tr_9K42",
"idempotencyKey": "vendor-run-2026-06-001",
"entries": [
{
"account": "wallet_kes_184250.available",
"direction": "debit",
"amount": "2500.00",
"currency": "KES"
},
{
"account": "partner_settlement.pending",
"direction": "credit",
"amount": "2500.00",
"currency": "KES"
}
],
"createdAt": "2026-06-03T09:20:00Z"
}Balance states
Customer and operator screens need to explain what funds can be used now and what is still settling, held, or reserved.
| State | Meaning | Typical user message |
|---|---|---|
| available | Funds can be used immediately | Ready to spend or send |
| pending | Rail or partner settlement is not final | Still settling |
| reserved | Held for approval, dispute, or risk review | Temporarily held |
| failed | Movement did not complete | Transfer failed |
| reversed | Movement was undone after earlier posting | Transfer reversed |
Continuous matching
Reconciliation compares Mozaca ledger state with rail, bank, mobile-money, custody-provider, accounting, and webhook evidence as events arrive.
Unmatched items need owner, reason, age, amount, rail, and next action so operations teams do not reconcile from screenshots.
- 01
Collect evidence
Ingest ledger events, rail callbacks, statements, provider reports, and accounting records.
- 02
Match deterministically
Use rail reference, amount, currency, counterparty, timestamp, and internal operation ID.
- 03
Queue exceptions
Expose mismatches with reason, owner, SLA, and audit trail.
- 04
Export evidence
Produce statement, reconciliation, board, regulator, or accounting packs.
Related docs