# Banking Overview

The banking layer: wallets, deposits, withdrawals, transfers, fees, and limits built on top of the double-entry ledger.

URL: https://docs.shiwake.app/docs/banking



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 [#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 [#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
```

<Callout type="info">
  All amounts are in **minor units** (e.g. pesewas for GHS, cents for USD).
  An amount of `50000` in GHS means GHS 500.00.
</Callout>

Provider-agnostic design [#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 [#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](/docs/api/authentication) for details.

Idempotency [#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](/docs/api/idempotency) for the general pattern.

What's in this section [#whats-in-this-section]

<Cards>
  <Card title="Wallet Products" href="/docs/banking/wallet-products" description="Product templates that define wallet behavior" />

  <Card title="Wallets" href="/docs/banking/wallets" description="Create and manage wallets for your users" />

  <Card title="Deposits" href="/docs/banking/deposits" description="Move money into wallets" />

  <Card title="Withdrawals" href="/docs/banking/withdrawals" description="Two-step hold/capture withdrawal flow" />

  <Card title="Transfers" href="/docs/banking/transfers" description="Wallet-to-wallet atomic transfers" />

  <Card title="Fee Engine" href="/docs/banking/fees" description="Configurable fee schedules with simulation" />

  <Card title="Transaction Limits" href="/docs/banking/limits" description="Per-transaction, daily, weekly, and monthly limits" />

  <Card title="Suspense" href="/docs/banking/suspense" description="Handle unattributed funds and reconciliation" />

  <Card title="Statements & Reports" href="/docs/banking/statements" description="Wallet statements and summary reports" />

  <Card title="Audit Log" href="/docs/banking/audit" description="Tenant-scoped banking audit trail" />
</Cards>
