Skip to main content
Your wallet holds the money you’ve paid in to fund your customers’ accounts. You move money from it to one account at a time with an allocation.

​
How your wallet is funded

  1. You pay the funds in, as agreed with us.
  2. When the funds are confirmed as received, we credit your wallet. There’s no API call for this step.
  3. The credit appears in credited_kobo and available_kobo on GET /v1/wallet.
Each bank transfer is credited once, however often it’s reported to us.

​
Allocate to an account

POST /v1/allocations moves an amount from your wallet to one of your accounts at the broker. It needs an Idempotency-Key.
Request body
We check your wallet and reserve the amount in one step, so two allocations can never both spend the same money. Then we send the allocation to the broker once. If your wallet doesn’t hold the amount, you get 422 wallet_too_low and nothing is stored. One allocation can be at most ₦100,000,000, and your allocations each day are capped too. See Limits.

​
The four figures

GET /v1/wallet returns four figures, all read from your wallet’s ledger at the same moment: This always holds: available_kobo = credited_kobo minus allocated_kobo minus reserved_kobo
Example
The ledger behind these figures is append-only. Credits, reserves, bookings and returns are added as new entries, and nothing is ever changed or deleted.

​
Your wallet and an account’s balance

Your wallet is ours: we keep its ledger. An account’s balance is the broker’s: GET /v1/accounts/{account}/balance returns it as the broker reports it. After an allocation is booked, the amount shows in the account’s balance, and trades and charges then move that balance at the broker. The API doesn’t offer withdrawals from your wallet or from an account.