Wallets and sub-accounts
Keep money in separate wallets of your business, and choose which wallet a payment uses.
Every business has a primary wallet. Everything you do today uses it. Sub-accounts are optional. If you never create one, nothing changes.
What a sub-account is
- It belongs to your business, in the same environment as your key.
- It shares your verification level and your limits. A payment from a sub-account counts toward the same limits as a payment from the primary wallet.
- It has its own balance.
- Money that others send to your business does not go to it. See What lands in the primary wallet.
Create one
POST /v1/sub-accounts
Idempotency-Key: wallet-client-acme
{
"label": "Acme Stores",
"reference": "wallet-client-acme"
}
labelis 1 to 60 characters. It must be unique among your open wallets, or you get409 wallet_label_taken.referenceis yours, and unique within your business. A reference already in use is409 duplicate_reference.- There is no limit on how many sub-accounts you open.
The answer is 201:
{
"id": "6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f",
"type": "sub_account",
"label": "Acme Stores",
"reference": "wallet-client-acme",
"status": "active",
"balances": { "GHS": "0.00" },
"reserved": { "GHS": "0.00" },
"createdAt": "2026-11-02T09:00:00Z"
}
The values above only show the shape.
idis what you send aswalletIdand in wallet moves.balancesandreservedare by currency, in major units.reservedis money set aside and not free to spend.referencecan be missing on a wallet you did not create through the API.closedAtis there once the wallet is closed.
The type field
type |
What it is |
|---|---|
primary |
Your main wallet. There is one. It cannot be closed. |
sub_account |
A wallet made with POST /v1/sub-accounts. |
operational |
A wallet made in the merchant console. You can use it like any other wallet. |
List your wallets
GET /v1/sub-accounts?limit=50
This lists every wallet of your business, the primary first, then oldest first. limit is 1 to 200 and defaults to 50. Pass the nextAfter of one page as after to get the next. Keep going until nextAfter is absent.
GET /v1/sub-accounts/6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f
This reads one. An id that is not one of your wallets is 404.
To find a sub-account by the reference you gave it, so you don’t have to store our id:
GET /v1/sub-accounts?reference=wallet-client-acme
items holds that one wallet, or is empty when none has the reference.
GET /v1/wallet still answers as before.
Close one
POST /v1/sub-accounts/6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f/close
Idempotency-Key: close-wallet-client-acme
Only an empty wallet can be closed. Closing a wallet that is already closed is safe.
| Status | Code | Meaning |
|---|---|---|
| 422 | wallet_is_primary |
The primary wallet cannot be closed. |
| 422 | wallet_not_empty |
Money is held or reserved in it. Move it out first. See Moving money between sub-accounts. |
| 422 | wallet_has_pending_activity |
Money is still in flight. Wait for it to finish, then try again. |
Choose the wallet for a payment
These routes take an optional walletId, the id of one of your wallets:
| Route | What walletId means |
|---|---|
POST /v1/collections |
The wallet the money lands in. Not with provider ismartpay: a payment request is paid into your primary wallet. |
POST /v1/payouts |
The wallet the money is paid from. |
POST /v1/payout-batches |
One walletId for the whole batch. Every item is paid from it. A walletId on an item is 400. |
POST /v1/transfers |
The sending wallet. |
POST /v1/utility-purchases |
The wallet that pays, when funding.type is wallet. |
POST /v1/checkouts |
The wallet a mobile money payment lands in. It is checked when you create the checkout, so the key also needs wallets.read. |
For example, a payout from a sub-account:
POST /v1/payouts
Idempotency-Key: refund-4410
{
"reference": "refund-4410",
"walletId": "6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f",
"amount": "40.00",
"currency": "GHS",
"provider": "mtn",
"destination": { "type": "msisdn", "value": "233244123456" }
}
The other fields are the same as the route always took.
- Without
walletId, the primary wallet is used. This is exactly what happened before sub-accounts existed. - A closed wallet is
422 wallet_closed. - An id that is not one of your wallets is
404. - The response, the webhooks and
GET /v1/transactionscarrywalletIdwhen a wallet was named. See Transactions and events.
If you close a wallet that an open checkout names, mobile money payments on that checkout fail with wallet_closed. Cancel the checkout first.
A payment uses the wallet you name, so fund a sub-account before you pay from it. Use a wallet move to do that.
What lands in the primary wallet
Money that someone else sends does not choose a wallet. It lands in your primary wallet. That covers:
- A wallet transfer from another business.
- A payment request (provider
ismartpay). - A checkout paid with iSmartPay, by request or from an iSmartPay wallet.
If you want that money in a sub-account, move it afterwards with a wallet move.
Permissions
| To | The key needs |
|---|---|
| Create or close a sub-account | wallets.write |
| List or read sub-accounts | wallets.read |
wallets.write alone does not let a key list or read wallets. Using walletId on a route needs the permission that route already needs; on a checkout it also needs wallets.read.
Errors
As well as the common errors:
| Status | Code | What to do |
|---|---|---|
| 404 | not_found |
The wallet id is not one of your wallets. |
| 409 | wallet_label_taken |
Another open wallet has this label. Pick another. |
| 409 | duplicate_reference |
The reference belongs to another wallet. Use a new one. |
| 422 | wallet_closed |
The wallet is closed. Use another. |
| 422 | wallet_is_primary, wallet_not_empty, wallet_has_pending_activity |
See Close one. |