Transaction Ledger

Retrieve wallet transactions for the current workspace and environment. Includes top-ups, shipment fee deductions, and refunds. Supports cursor-based pagination and date range filtering.

---

Endpoint

GET/v1/wallet/transactions

Required permission: wallet:transactions:get

---

Query Parameters

Parameter	Type	Required	Description
limit	Integer	❌	Max records per page. Defaults to 20.
cursor	String	❌	Pagination cursor from a previous response.
startDate	String	❌	ISO 8601 start of the date range (e.g. 2026-07-01T00:00:00Z).
endDate	String	❌	ISO 8601 end of the date range (e.g. 2026-07-31T23:59:59Z).

When both startDate and endDate are omitted, all transactions for the environment are returned in reverse-chronological order.

---

Response

Top-level fields

Field	Type	Description
items	Array	List of transaction records.
nextCursor	String?	Cursor to fetch the next page. null when there are no more results.

Item fields

Field	Type	Description
id	String	Unique ledger entry ID (e.g. TNX_A1B2C3D4).
date	String	ISO 8601 UTC timestamp of the transaction.
type	String	Transaction category. TOPUP, SHIPMENT_FEE, or REFUND.
description	String	Human-readable summary of the transaction.
amount	Float	Transaction value in ₦.
balanceAfter	Float	Wallet balance immediately after this transaction.
reference	String?	Associated reference ID. shipment ID for fees/refunds, bank reference for top-ups.

---

Transaction Types

Value	When it appears
TOPUP	A wallet deposit was processed.
SHIPMENT_FEE	A shipment was booked and the fee was deducted.
REFUND	A shipment was canceled and the fee was returned.

---

{
"statusCode": 200,
"message": "Success",
"data": {
  "items": [
    {
      "id": "TNX_A1B2C3D4E5",
      "date": "2026-07-01T18:00:00Z",
      "type": "TOPUP",
      "description": "Prepaid Deposit via GTBank",
      "amount": 50000,
      "balanceAfter": 150000,
      "reference": "GTB2026070100987"
    },
    {
      "id": "TNX_B2C3D4E5F6",
      "date": "2026-07-01T17:42:00Z",
      "type": "SHIPMENT_FEE",
      "description": "Shipment fee for payment reference TCL-SB-3891829",
      "amount": 33040,
      "balanceAfter": 100000,
      "reference": "SHP_Z8F9A2B3C4"
    }
  ],
  "nextCursor": null
}
}