Deposits
Move money into wallets: synchronous flow with automatic fee deduction and limit enforcement.
A deposit credits a wallet with funds from the platform float. It is a synchronous, single-call operation: the journal entry posts immediately and the wallet balance updates in the same request.
Flow
Client → POST /banking/wallets/{id}/deposit
↓
Validate wallet (active, currency match)
↓
Check transaction limits
↓
Calculate fee (if fee schedule exists)
↓
Post journal entry:
Debit PLATFORM-FLOAT-{CCY} (asset ↑ money arrived)
Credit CLIENT-{ownerId} (liability ↑ we owe more)
[if fee > 0]
Debit CLIENT-{ownerId} (liability ↓ fee taken)
Credit FEE-REVENUE-{CCY} (revenue ↑ fee earned)
↓
Return completed transactionThe fee is deducted from the wallet in the same journal entry as the deposit. If you deposit 10,000 with a 100 fee, the wallet receives a net credit of 9,900.
The BankingTransaction object
Deposits and withdrawals share the same response shape:
{
"id": "btx_01HZ...",
"walletId": "wal_01HZ...",
"productId": "wp_01HZ...",
"type": "Deposit",
"status": "Completed",
"amount": 50000,
"feeAmount": 500,
"netAmount": 49500,
"currency": "GHS",
"channel": "paystack",
"externalReference": "psk_tx_abc123",
"description": "MoMo deposit",
"journalEntryId": "jen_01HZ...",
"holdId": null,
"failureReason": null,
"idempotencyKey": "8b7f9c2e-4d1a-4e6b-9c3a-1f2e3d4c5b6a",
"metadata": null,
"settledAt": "2026-04-07T12:00:00Z",
"completedAt": "2026-04-07T12:00:00Z",
"createdAt": "2026-04-07T12:00:00Z",
"updatedAt": null
}Prop
Type
Create a deposit
/api/v1/banking/wallets/{walletId}/depositIdempotency-KeyRequest body
Prop
Type
Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | yes | Deduplication key for this deposit |
X-Created-By | no | Actor identifier for audit trail |
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../deposit" \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: psk_tx_abc123" \
-H "X-Created-By: deposit-webhook" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "GHS",
"channel": "paystack",
"externalReference": "psk_tx_abc123",
"description": "MoMo deposit"
}'A natural idempotency key for deposits is the external transaction id from your payment provider. If the webhook fires twice, the second call returns the existing transaction instead of double-crediting.
Status codes
| Code | When |
|---|---|
201 | Deposit created and completed |
200 | Idempotent replay: returning existing transaction |
404 | Wallet not found |
422 | Validation error, wallet frozen/closed, currency mismatch, limit exceeded, banking not bootstrapped |
List transactions
/api/v1/banking/transactionsReturns both deposits and withdrawals.
Query parameters
Prop
Type
curl "https://api.shiwake.example.com/api/v1/banking/transactions?walletId=wal_01HZ...&type=Deposit&take=20" \
-H "X-Api-Key: sk_live_..."Get a transaction
/api/v1/banking/transactions/{id}curl "https://api.shiwake.example.com/api/v1/banking/transactions/btx_01HZ..." \
-H "X-Api-Key: sk_live_..."Last updated on