ShiwakeDocs

Transfers

Atomic wallet-to-wallet transfers: one journal entry, no intermediate state.

A transfer moves money between two wallets in a single atomic operation. Unlike withdrawals, there is no hold/capture step: the journal entry posts immediately and both balances update in the same request.

How it works

Client → POST /banking/transfers
         ↓
     Validate sender ≠ receiver
     Validate both wallets active, same currency
         ↓
     Post journal entry:
       Debit  CLIENT-{senderId}     (sender owes less)
       Credit CLIENT-{receiverId}   (receiver owed more)
         ↓
     Return completed transfer

The platform float is not touched: money moves directly between liability accounts.

Transfers are currently fee-free. The feeAmount field is always 0.

The Transfer object

{
  "id": "txf_01HZ...",
  "senderWalletId": "wal_01HZ...",
  "receiverWalletId": "wal_02HZ...",
  "amount": 15000,
  "feeAmount": 0,
  "netAmount": 15000,
  "currency": "GHS",
  "status": "Completed",
  "journalEntryId": "jen_01HZ...",
  "reference": "rent-april-2026",
  "description": "Monthly rent payment",
  "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": null,
  "createdAt": "2026-04-07T12:00:00Z",
  "updatedAt": null
}

Prop

Type


Create a transfer

POST/api/v1/banking/transfersIdempotency-Key

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/transfers" \
  -H "X-Api-Key: sk_live_..." \
  -H "Idempotency-Key: rent-april-2026" \
  -H "X-Created-By: payment-service" \
  -H "Content-Type: application/json" \
  -d '{
    "senderWalletId": "wal_01HZ...",
    "receiverWalletId": "wal_02HZ...",
    "amount": 15000,
    "currency": "GHS",
    "reference": "rent-april-2026",
    "description": "Monthly rent payment"
  }'

Status codes

CodeWhen
201Transfer completed
200Idempotent replay
404Sender or receiver wallet not found
422Same wallet, wallet frozen/closed, currency mismatch, insufficient balance

List transfers

GET/api/v1/banking/transfers

Prop

Type


Get a transfer

GET/api/v1/banking/transfers/{id}
Edit on GitHub

Last updated on

On this page