Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview
On this page

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"
}
  • label is 1 to 60 characters. It must be unique among your open wallets, or you get 409 wallet_label_taken.
  • reference is yours, and unique within your business. A reference already in use is 409 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.

  • id is what you send as walletId and in wallet moves.
  • balances and reserved are by currency, in major units. reserved is money set aside and not free to spend.
  • reference can be missing on a wallet you did not create through the API.
  • closedAt is 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/transactions carry walletId when 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.

Was this page helpful?