ShiwakeDocs

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 conceptBuilt on
WalletLiability account + metadata (owner, tier, product, status)
DepositJournal entry: debit PLATFORM-FLOAT, credit wallet account
WithdrawalHold → capture journal entry: debit wallet, credit PLATFORM-FLOAT
TransferJournal entry: debit sender wallet, credit receiver wallet
FeeExtra journal lines: debit wallet, credit FEE-REVENUE
SuspenseJournal 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 funds

When a wallet is opened, a liability account is created from the product's accountCodeTemplate:

CLIENT-{ownerId}         Liability   One per wallet

All 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:

  1. Banking layer: the IdempotencyKey on the transaction/transfer prevents duplicate submissions.
  2. 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

Edit on GitHub

Last updated on

On this page