Moving money between sub-accounts
Move money between your own wallets in one step.
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.
Move money
POST /v1/wallet-moves
Idempotency-Key: move-9001
{
"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"
}
referenceis yours, and unique for each move.- Both wallets must be your own. The primary wallet counts. Its
idis inGET /v1/sub-accounts. currencyisGHSonly.noteis optional.
The answer is 201:
{
"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.
Moves and transfers
| Wallet move | Wallet transfer | |
|---|---|---|
| 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:
| 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. |