# Deposits

Move money into wallets: synchronous flow with automatic fee deduction and limit enforcement.

URL: https://docs.shiwake.app/docs/banking/deposits



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 [#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
```

<Callout type="info">
  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.
</Callout>

The BankingTransaction object [#the-bankingtransaction-object]

Deposits and [withdrawals](/docs/banking/withdrawals) share the same
response shape:

```json
{
  "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
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Transaction identifier&#x22; },
  walletId: { type: &#x22;string&#x22;, required: true, description: &#x22;The wallet that received the deposit&#x22; },
  type: { type: &#x22;string&#x22;, required: true, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  status: { type: &#x22;string&#x22;, required: true, description: <><code>Processing</code>, <code>Completed</code>, <code>Failed</code></> },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Gross amount in minor units&#x22; },
  feeAmount: { type: &#x22;long&#x22;, required: true, description: &#x22;Fee deducted (0 if no fee schedule)&#x22; },
  netAmount: { type: &#x22;long&#x22;, required: true, description: <><code>amount - feeAmount</code></> },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  channel: { type: &#x22;string&#x22;, required: true, description: &#x22;Provider-agnostic channel tag&#x22; },
  externalReference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Your upstream reference&#x22; },
  journalEntryId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;The ledger entry that moved the money&#x22; },
  holdId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Only set for withdrawals&#x22; },
  failureReason: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Why it failed, if applicable&#x22; },
  idempotencyKey: { type: &#x22;string&#x22;, required: true, description: &#x22;Deduplication key&#x22; },
  settledAt: { type: &#x22;datetime | null&#x22;, required: true, description: &#x22;When the ledger entry posted&#x22; },
  completedAt: { type: &#x22;datetime | null&#x22;, required: true, description: &#x22;When the transaction reached terminal state&#x22; },
}"
/>

***

Create a deposit [#create-a-deposit]

<Endpoint method="POST" path="/api/v1/banking/wallets/{walletId}/deposit" />

Request body [#request-body]

<TypeTable
  type="{
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount in minor units (must be positive)&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code, must match wallet&#x22; },
  channel: { type: &#x22;string&#x22;, required: true, description: <>e.g. <code>&#x22;paystack&#x22;</code>, <code>&#x22;momo&#x22;</code>, <code>&#x22;bank_transfer&#x22;</code></> },
  externalReference: { type: &#x22;string&#x22;, description: &#x22;Your upstream transaction reference&#x22; },
  description: { type: &#x22;string&#x22;, description: &#x22;Human-readable description&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

Headers [#headers]

| Header            | Required | Description                        |
| ----------------- | -------- | ---------------------------------- |
| `Idempotency-Key` | yes      | Deduplication key for this deposit |
| `X-Created-By`    | no       | Actor identifier for audit trail   |

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "btx_01HZ...",
        "walletId": "wal_01HZ...",
        "type": "Deposit",
        "status": "Completed",
        "amount": 50000,
        "feeAmount": 500,
        "netAmount": 49500,
        "currency": "GHS",
        "channel": "paystack",
        "externalReference": "psk_tx_abc123",
        "journalEntryId": "jen_01HZ...",
        "settledAt": "2026-04-07T12:00:00Z",
        "completedAt": "2026-04-07T12:00:00Z",
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="info">
  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.
</Callout>

Status codes [#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 [#list-transactions]

<Endpoint method="GET" path="/api/v1/banking/transactions" />

Returns both deposits and withdrawals.

Query parameters [#query-parameters]

<TypeTable
  type="{
  walletId: { type: &#x22;string&#x22;, description: &#x22;Filter by wallet&#x22; },
  type: { type: &#x22;string&#x22;, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  status: { type: &#x22;string&#x22;, description: <><code>Processing</code>, <code>Completed</code>, <code>Failed</code></> },
  channel: { type: &#x22;string&#x22;, description: &#x22;Filter by channel&#x22; },
  from: { type: &#x22;datetime&#x22;, description: &#x22;Start of date range&#x22; },
  to: { type: &#x22;datetime&#x22;, description: &#x22;End of date range&#x22; },
  take: { type: &#x22;int&#x22;, description: &#x22;Page size (default 100)&#x22; },
}"
/>

```bash
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-a-transaction]

<Endpoint method="GET" path="/api/v1/banking/transactions/{id}" />

```bash
curl "https://api.shiwake.example.com/api/v1/banking/transactions/btx_01HZ..." \
  -H "X-Api-Key: sk_live_..."
```
