​
Wallet balance semantics

The wallet has three balance fields — only available_balance should be shown on the main dashboard:
FieldMeaning
available_balanceSpendable right now — can fund escrows or withdraw
locked_balanceHeld in active escrow locks + KYC-gated received funds
total_balanceavailable + locked — informational only
GET /wallet-get
Authorization: Bearer <token>

​
Topping up

​
Via saved card

POST /wallet-topup
{ "amount": 50000 }

​
Via bank transfer

Use the user’s virtual account number from GET /virtual-account-get. No API call needed — Paystack handles the credit automatically via webhook.

​
Withdrawing

POST /wallet-withdraw
{
  "amount": 50000
}
Destination resolution order:
  1. one_time_payout in request body (highest priority)
  2. payout_account_id in request body
  3. User’s default payout account
Transfers are processed via Paystack. The available_balance is deducted immediately — a pending transaction is created. Confirmation arrives async via the transfer.success webhook. If the transfer fails, the deducted amount is automatically reversed and the transaction marked failed.
See the Payments & Fund Releases guide for the full withdrawal flow, one-time payouts, and auto-withdrawal details.

​
Auto-withdrawal

Enable auto-withdrawal to automatically send released escrow funds to the default payout account: 
PATCH /wallet-toggle-auto-withdraw
{ "enabled": true }

​
Managing payout accounts

​
Add a bank account

First verify it: 
GET /payout-verify?bank_code=044&account_number=0123456789
Then save it: 
POST /payout-add
{
  "bank_code": "044",
  "bank_name": "Access Bank",
  "account_number": "0123456789",
  "account_name": "Ade Johnson"
}
Account numbers are masked in all responses (e.g. ******6789).

​
Set a default

PATCH /payout-set-default
{ "id": "<id>" }

​
Delete

DELETE /payout-delete?id=<id>

​
Virtual account

Every user who has passed Tier 1 KYC gets a dedicated virtual bank account: 
POST /virtual-account-create    # creates it
GET  /virtual-account-get       # returns the number + bank details
Share this account number with the user — any bank transfer to it credits their wallet automatically.