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 transferThe 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-KeyRequest 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
| Code | When |
|---|---|
201 | Transfer completed |
200 | Idempotent replay |
404 | Sender or receiver wallet not found |
422 | Same wallet, wallet frozen/closed, currency mismatch, insufficient balance |
List transfers
GET
/api/v1/banking/transfersProp
Type
Get a transfer
GET
/api/v1/banking/transfers/{id}Edit on GitHub
Last updated on