Banking Overview
The banking layer: wallets, deposits, withdrawals, transfers, fees, and limits built on top of the double-entry ledger.
The banking layer is an opinionated, provider-agnostic abstraction built on top of the core double-entry ledger. It gives you wallets, deposits, withdrawals, transfers, fee schedules, transaction limits, suspense management, and reporting: all backed by immutable journal entries.
How it relates to the core ledger
The core ledger gives you accounts, journal entries, holds, and reconciliation. The banking layer uses those primitives to model familiar fintech concepts:
| Banking concept | Built on |
|---|---|
| Wallet | Liability account + metadata (owner, tier, product, status) |
| Deposit | Journal entry: debit PLATFORM-FLOAT, credit wallet account |
| Withdrawal | Hold → capture journal entry: debit wallet, credit PLATFORM-FLOAT |
| Transfer | Journal entry: debit sender wallet, credit receiver wallet |
| Fee | Extra journal lines: debit wallet, credit FEE-REVENUE |
| Suspense | Journal entries moving funds through the SUSPENSE account |
Every money movement produces a balanced journal entry: the banking layer never bypasses the double-entry engine.
Account structure per tenant
When a tenant bootstraps banking (via POST /api/v1/banking/bootstrap),
three system accounts are created per currency:
PLATFORM-FLOAT-{CCY} Asset Where real money sits
FEE-REVENUE-{CCY} Revenue Where fees accumulate
SUSPENSE-{CCY} Asset Unattributed inbound fundsWhen a wallet is opened, a liability account is created from the product's
accountCodeTemplate:
CLIENT-{ownerId} Liability One per walletAll amounts are in minor units (e.g. pesewas for GHS, cents for USD).
An amount of 50000 in GHS means GHS 500.00.
Provider-agnostic design
The banking layer does not couple to any specific payment provider. Instead
of a provider entity, every deposit, withdrawal, and suspense item carries a
free-form channel string (e.g. "paystack", "hubtel", "momo",
"bank_transfer", "cash"). Your application chooses the channel. The
ledger doesn't interpret it.
This means you can:
- Add a new payment provider without a migration
- Use different providers per tenant
- Mix automated and manual channels in the same reporting
Authentication
All banking endpoints require tenant-scoped authentication
(X-Api-Key header). Platform-level endpoints (reports, scheduled jobs)
require platform-admin JWT tokens.
See Authentication for details.
Idempotency
All mutating banking endpoints require an Idempotency-Key header. The
banking layer enforces two layers of idempotency:
- Banking layer: the
IdempotencyKeyon the transaction/transfer prevents duplicate submissions. - Ledger layer: a derived key (e.g.
banking:{txId},transfer:{id}) prevents duplicate journal entries.
See Idempotency for the general pattern.
What's in this section
Wallet Products
Product templates that define wallet behavior
Wallets
Create and manage wallets for your users
Deposits
Move money into wallets
Withdrawals
Two-step hold/capture withdrawal flow
Transfers
Wallet-to-wallet atomic transfers
Fee Engine
Configurable fee schedules with simulation
Transaction Limits
Per-transaction, daily, weekly, and monthly limits
Suspense
Handle unattributed funds and reconciliation
Statements & Reports
Wallet statements and summary reports
Audit Log
Tenant-scoped banking audit trail
Last updated on