Wallets

Each customer has one wallet per currency. A wallet tracks posted balance, available funds, and active holds.

The wallet object

{
  "id": "01M2S17...",
  "customer_id": "01M2S17...",
  "currency": "NGN",
  "balance_minor": 500000,
  "available_minor": 450000,
  "held_minor": 50000,
  "created_at": "2026-09-18T01:13:51Z"
}

Field	Type	Notes
`balance_minor`	int	Posted ledger balance (never negative)
`available_minor`	int	Balance minus active holds
`held_minor`	int	Funds reserved by in-flight transactions

Balances come from the ledger: they are not stored counters. A wallet balance is always reconcilable to its journal entries.

Holds

A transaction that has not settled places a hold on funds rather than debiting them. The hold:

reduces available_minor immediately
converts to a debit on completion, or releases on failure/expiry

You never see available < 0: the hold is what makes concurrency safe: two simultaneous requests cannot spend the same funds twice.

Funding a wallet

Customers fund wallets through the methods enabled for their country:

Bank transfer: a static virtual account per customer; inbound credits post automatically
Card / mobile money: a payment that settles into the wallet
Admin credit: operations funding (sandbox and approved flows)

Virtual accounts are funding instruments

A static virtual account is a wallet-funding rail: it is never offered as a checkout payment method. Inbound credits arrive via webhook and post to the wallet.

Multi-currency

Each currency is a separate wallet. Converting between them goes through Exchange: an explicit quote, a posted FX leg, and both wallets' balances updated atomically.

Endpoints

Method	Path	Description
GET	`/v1/wallets/{id}`	Retrieve
GET	`/v1/customers/{id}/wallets`	List customer wallets