ShiwakeDocs

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 transaction

The 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

POST/api/v1/banking/wallets/{walletId}/depositIdempotency-Key

Request body

Prop

Type

Headers

HeaderRequiredDescription
Idempotency-KeyyesDeduplication key for this deposit
X-Created-BynoActor 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

CodeWhen
201Deposit created and completed
200Idempotent replay: returning existing transaction
404Wallet not found
422Validation error, wallet frozen/closed, currency mismatch, limit exceeded, banking not bootstrapped

List transactions

GET/api/v1/banking/transactions

Returns 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

GET/api/v1/banking/transactions/{id}
curl "https://api.shiwake.example.com/api/v1/banking/transactions/btx_01HZ..." \
  -H "X-Api-Key: sk_live_..."
Edit on GitHub

Last updated on

On this page