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

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"
}
  • 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:

{
  "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.

Was this page helpful?