GET /api/wallets/:walletId/ledgers — wallet ledger entries

Retrieve paginated ledger entries for a wallet. Each entry records a topup, debit, or refund with the resulting balance after the change.

Retrieve the double-entry ledger for a wallet, paginated and sorted newest-first. Every balance-changing event — fund top-ups, approved payment debits, and refunds — produces a ledger entry with the resulting balanceAfter so you can reconstruct the wallet’s balance at any point in time. Use this endpoint for reconciliation, audit exports, or building a running-balance display in your dashboard.

Endpoint

GET /api/wallets/:walletId/ledgers

Authentication

Requires a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

Path Parameters

walletId · string · required

The UUID of the wallet whose ledger you want to retrieve.

---

Query Parameters

page · integer · default: "1"

The page number to retrieve. Pages are 1-indexed.

pageSize · integer · default: "10"

The number of ledger entries to return per page.

---

Response 200 OK

The response envelope contains success: true, a data array of ledger entries, and a pagination object with totals.

success · boolean

Always true for a successful response.

data · object[]

Array of ledger entry objects for the requested page, sorted newest-first.

Show ledger entry fields

data[].id · string

Unique ledger entry UUID.

data[].walletId · string

The wallet this entry belongs to.

data[].type · string

The type of balance event. One of:

• "topup" — funds were credited to the wallet (e.g. bank transfer received).
• "debit" — funds were debited for an approved payment.
• "refund" — a previous debit was reversed and funds returned to the wallet.

data[].amount · integer

The absolute value of the balance change, in kobo. Always positive regardless of direction — use type to determine whether the balance increased or decreased.

data[].balanceAfter · integer

The wallet balance in kobo immediately after this entry was applied. Use this field to render a running balance column.

data[].transactionId · string | null

The UUID of the associated transaction record, if this entry was produced by a payment authorisation or refund. null for topup entries.

data[].reference · string | null

A human-readable reference string, or null when no reference is available. For top-ups this is typically the inbound bank transfer reference; for debits and refunds it mirrors the transaction reference.

data[].createdAt · string

ISO 8601 timestamp of when this ledger entry was created.

pagination · object

Metadata about the paginated result set.

Show pagination fields

pagination.page · integer

The current page number.

pagination.pageSize · integer

The number of entries per page.

pagination.totalCount · integer

Total number of ledger entries across all pages.

pagination.totalPages · integer

Total number of pages at the current pageSize.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "led_f1e2d3c4-b5a6-4789-bcde-f01234567890",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "refund",
      "amount": 345000,
      "balanceAfter": 1595000,
      "transactionId": "txn_d4e5f6a7-b8c9-4012-8def-012345678901",
      "reference": "AXS-20250715-0041-REFUND",
      "createdAt": "2025-07-15T13:27:05Z"
    },
    {
      "id": "led_a0b1c2d3-e4f5-4678-abcd-e09876543210",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "debit",
      "amount": 345000,
      "balanceAfter": 1250000,
      "transactionId": "txn_d4e5f6a7-b8c9-4012-8def-012345678901",
      "reference": "AXS-20250715-0041",
      "createdAt": "2025-07-15T11:03:44Z"
    },
    {
      "id": "led_b2c3d4e5-f6a7-4890-cdef-123456789012",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "topup",
      "amount": 2000000,
      "balanceAfter": 1595000,
      "transactionId": null,
      "reference": "TRF-2025071501-WEMA",
      "createdAt": "2025-07-15T09:55:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 12,
    "totalPages": 2
  }
}

---

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid Session JWT.
404	WALLET_NOT_FOUND	No wallet exists with the supplied walletId.

{
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "No wallet found with ID wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321."
  }
}