---
title: Moving money between sub-accounts
description: Move money between your own wallets in one step.
---

:::note[In a nutshell]
A wallet move shifts money from one wallet of your business to another. It happens in one step, with no fee and no PIN. It does not count toward your limits.
:::

Use it to fund a sub-account, to empty one before you close it, or to pull money out of the primary wallet for a client. For wallets and `walletId`, see [Wallets and sub-accounts](/guides/wallets-and-sub-accounts).

## Move money

```http
POST /v1/wallet-moves
Idempotency-Key: move-9001
```

```json
{
  "reference": "move-9001",
  "fromWalletId": "1b2c3d4e-5f60-4718-9293-a4b5c6d7e8f9",
  "toWalletId": "6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f",
  "amount": "500.00",
  "currency": "GHS",
  "note": "Fund the Acme wallet"
}
```

- `reference` is yours, and unique for each move.
- Both wallets must be your own. The primary wallet counts. Its `id` is in `GET /v1/sub-accounts`.
- `currency` is `GHS` only.
- `note` is optional.

The answer is `201`:

```json
{
  "reference": "move-9001",
  "status": "completed",
  "fromWalletId": "1b2c3d4e-5f60-4718-9293-a4b5c6d7e8f9",
  "toWalletId": "6f0c2d4e-8a1b-4c3d-9e5f-1a2b3c4d5e6f",
  "amount": "500.00",
  "currency": "GHS",
  "note": "Fund the Acme wallet",
  "createdAt": "2026-11-02T10:00:00Z",
  "completedAt": "2026-11-02T10:00:00Z"
}
```

The values above only show the shape. `failureReason` is there when a move fails, and `completedAt` when it finishes.

Read one later with `GET /v1/wallet-moves/move-9001`.

## Fees and limits

- A move carries no fee.
- A move does not count toward your limits.
- It needs no PIN.

## Retrying

If a request fails, times out or returns `5xx`, send the same reference and body again, with the same `Idempotency-Key`. Do not retry with a new reference. A new reference is a new move.

## In your transactions

A move shows in `GET /v1/transactions` with `kind` `wallet_move`. Filter with `kind=wallet_move`, or with `walletId` to see what touched one wallet. See [Transactions and events](/guides/transactions-and-events).

## Moves and transfers

| | Wallet move | [Wallet transfer](/guides/wallet-transfers) |
| --- | --- | --- |
| Pays | Another wallet of your own business | Another iSmartPay business |
| Found by | `fromWalletId` and `toWalletId` | The recipient's handle |
| Fee | None | None |
| Counts toward limits | No | Yes |
| Other side is told | No, it is your own money | Yes, with `transfer.received` |

Use a move to shift money inside your business. Use a transfer to pay someone else.

## Permissions

| To              | The key needs          |
| --------------- | ---------------------- |
| Move money      | `wallettransfer.write` |
| Read a move     | `wallettransfer.read`  |

## Errors

As well as the [common errors](/guides/errors):

| Status | Code                     | What to do                                                  |
| ------ | ------------------------ | ----------------------------------------------------------- |
| 400    | `invalid_input`          | A field is malformed, or the same wallet is on both sides. Read `message`. |
| 404    | `not_found`              | A wallet id is not one of your wallets.                     |
| 422    | `insufficient_funds`     | The source wallet holds less than `amount`.                 |
| 422    | `currency_not_supported` | Only `GHS` is supported.                                    |
| 422    | `wallet_closed`          | One of the wallets is closed.                               |
