---
title: Wallets and sub-accounts
description: Keep money in separate wallets of your business, and choose which wallet a payment uses.
---

:::note[In a nutshell]
A sub-account is another wallet of your business. It is not a separate merchant. It sits under your one verification and your limits. Use it to keep money apart for your own bookkeeping, for example one wallet per client or per product.
:::

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](#what-lands-in-the-primary-wallet).

## Create one

```http
POST /v1/sub-accounts
Idempotency-Key: wallet-client-acme
```

```json
{
  "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`:

```json
{
  "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

```http
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.

```http
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`:

```http
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

```http
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](/guides/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:

```http
POST /v1/payouts
Idempotency-Key: refund-4410
```

```json
{
  "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](/guides/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](/guides/moving-money-between-sub-accounts) 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](/guides/moving-money-between-sub-accounts).

## 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](/guides/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](#close-one). |
