# Statements & Reports

Wallet statements, tenant summaries, and platform-wide reports: all returned as JSON.

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



Three reporting endpoints return structured JSON data for different
audiences: wallet holders, tenant operators, and platform administrators.

Wallet statement [#wallet-statement]

<Endpoint method="GET" path="/api/v1/banking/wallets/{walletId}/statement?from=2026-03-01&to=2026-03-31" />

Returns a detailed statement for a single wallet over a date range,
including opening/closing balances, line-by-line entries with running
balance, and deposit/withdrawal/transfer/fee summaries.

Query parameters [#query-parameters]

<TypeTable
  type="{
  from: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Start of period (inclusive)&#x22; },
  to: { type: &#x22;datetime&#x22;, required: true, description: &#x22;End of period (inclusive)&#x22; },
}"
/>

How the opening balance is computed [#how-the-opening-balance-is-computed]

The opening balance is the sum of all double-entry ledger lines on the
wallet's account **before** the `from` date. Credits add, debits subtract
(because wallet accounts are credit-normal liabilities).

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

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

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../statement?from=2026-03-01&to=2026-03-31" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "data": {
        "walletId": "wal_01HZ...",
        "ownerId": "user_42",
        "displayName": "Kwame's Savings",
        "productName": "Savings Account",
        "tier": "Basic",
        "currency": "GHS",
        "from": "2026-03-01",
        "to": "2026-03-31",
        "openingBalance": 150000,
        "closingBalance": 225000,
        "totalDeposits": 100000,
        "totalWithdrawals": 25000,
        "totalFeesCharged": 1500,
        "totalTransfersIn": 10000,
        "totalTransfersOut": 8500,
        "lines": [
          {
            "date": "2026-03-05T09:15:00Z",
            "type": "Credit",
            "description": "MoMo deposit",
            "reference": "psk_tx_abc123",
            "debit": 0,
            "credit": 50000,
            "runningBalance": 200000
          },
          {
            "date": "2026-03-05T09:15:00Z",
            "type": "Debit",
            "description": "Fee",
            "reference": "psk_tx_abc123",
            "debit": 500,
            "credit": 0,
            "runningBalance": 199500
          },
          {
            "date": "2026-03-12T14:30:00Z",
            "type": "Debit",
            "description": "Cash out to MoMo",
            "reference": "momo_ref_xyz789",
            "debit": 25000,
            "credit": 0,
            "runningBalance": 174500
          }
        ]
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Statement line fields [#statement-line-fields]

<TypeTable
  type="{
  date: { type: &#x22;datetime&#x22;, required: true, description: &#x22;When the entry was posted&#x22; },
  type: { type: &#x22;string&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code></> },
  description: { type: &#x22;string&#x22;, required: true, description: &#x22;Entry description or journal description&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Journal entry reference&#x22; },
  debit: { type: &#x22;long&#x22;, required: true, description: &#x22;Debit amount (money leaving wallet)&#x22; },
  credit: { type: &#x22;long&#x22;, required: true, description: &#x22;Credit amount (money entering wallet)&#x22; },
  runningBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Balance after this line&#x22; },
}"
/>

***

Tenant summary [#tenant-summary]

<Endpoint method="GET" path="/api/v1/banking/reports/summary?from=2026-03-01&to=2026-03-31&currency=GHS" />

Aggregated report for the current tenant: transaction volumes, fee
revenue, channel breakdown, and wallet counts by product.

Query parameters [#query-parameters-1]

<TypeTable
  type="{
  from: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Start of period&#x22; },
  to: { type: &#x22;datetime&#x22;, required: true, description: &#x22;End of period&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code&#x22; },
}"
/>

```json
{
  "code": 200,
  "data": {
    "from": "2026-03-01",
    "to": "2026-03-31",
    "currency": "GHS",
    "totalDeposits": 50000000,
    "depositCount": 420,
    "totalWithdrawals": 15000000,
    "withdrawalCount": 150,
    "totalTransfers": 8000000,
    "transferCount": 200,
    "totalFeesCollected": 750000,
    "netFlow": 35000000,
    "channelBreakdown": [
      {
        "channel": "paystack",
        "depositTotal": 30000000,
        "depositCount": 250,
        "withdrawalTotal": 10000000,
        "withdrawalCount": 100
      },
      {
        "channel": "momo",
        "depositTotal": 20000000,
        "depositCount": 170,
        "withdrawalTotal": 5000000,
        "withdrawalCount": 50
      }
    ],
    "walletCounts": [
      {
        "productName": "Savings Account",
        "productCode": "SAVINGS",
        "activeCount": 1250,
        "frozenCount": 12,
        "closedCount": 45
      }
    ]
  }
}
```

***

Platform summary [#platform-summary]

<Endpoint method="GET" path="/api/v1/platform/reports/summary?from=2026-03-01&to=2026-03-31" />

<Callout type="warn">
  This endpoint requires **platform-admin** authentication (JWT with
  `platform-admin` role), not a tenant API key.
</Callout>

Cross-tenant summary for platform operators. Iterates all tenants and
returns transaction volume, fee revenue, and wallet counts per tenant.

Query parameters [#query-parameters-2]

<TypeTable
  type="{
  from: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Start of period&#x22; },
  to: { type: &#x22;datetime&#x22;, required: true, description: &#x22;End of period&#x22; },
}"
/>

```json
{
  "code": 200,
  "data": {
    "from": "2026-03-01",
    "to": "2026-03-31",
    "tenants": [
      {
        "tenantId": "ten_01HZ...",
        "tenantName": "Acme Fintech",
        "totalTransactionVolume": 65000000,
        "transactionCount": 570,
        "totalFeeRevenue": 750000,
        "activeWalletCount": 1250
      },
      {
        "tenantId": "ten_02HZ...",
        "tenantName": "BetaPay",
        "totalTransactionVolume": 30000000,
        "transactionCount": 280,
        "totalFeeRevenue": 350000,
        "activeWalletCount": 600
      }
    ],
    "totalVolume": 95000000,
    "totalFees": 1100000,
    "totalActiveWallets": 1850
  }
}
```
