Wallet Balance History

Retrieves the transaction history of a specific wallet. This endpoint allows you to view wallet activity and track how the wallet balance changes over time, including credits, debits, transaction types, and balances before and after each transaction.

Endpoint

GET {{base_url}}/api/v1/user/wallet/history

Headers

Header	Required	Description
`X-merchant-ref`	Yes	Your unique merchant reference.

Example Request

'{{base_url}}/api/v1/user/wallet/history?user_ref={USER_REF}&wallet_id={{wallet_id}}&date_from=2026-09-18&date_to=2026-10-20&page=1&no_records=10&sort=desc'

Query Parameters

Parameter	Required	Type	Description
`user_ref`	Yes	String	Reference of the user who owns the wallet.
`wallet_id`	Yes	String	ID of the wallet whose transaction history is being retrieved.
`date_from`	No	Date	Start date for the transaction history. Format: `YYYY-MM-DD`.
`date_to`	No	Date	End date for the transaction history. Format: `YYYY-MM-DD`.
`page`	No	Integer	Page number for paginated results.
`no_records`	No	Integer	Number of records to return per page.
`sort`	No	String	Sort order for the results. Accepted values: `asc` or `desc`.

Response

`200 OK`

{
  "status": "success",
  "message": "Retrieved successfully",
  "data": [
    {
      "date": "2026-10-06T11:13:46Z",
      "txn_type": "utility_payment",
      "type": "debit",
      "amount": 7,
      "currency": "NGN",
      "txn_ref": "8b2121ce-2d50-44dc-b6b4-c6889d046d4f-debit",
      "available_balance_before": 689.5,
      "available_balance_after": 682.5,
      "ledger_balance_before": 0,
      "ledger_balance_after": 0,
      "status": "instant"
    },
    {
      "date": "2026-10-06T10:30:50Z",
      "txn_type": "collection",
      "type": "credit",
      "amount": 700,
      "currency": "NGN",
      "txn_ref": "vapp_0002_1_1_1_1_2_1_1",
      "available_balance_before": 0,
      "available_balance_after": 0,
      "ledger_balance_before": 0,
      "ledger_balance_after": 689.5,
      "status": "settled",
      "settle_at": "2026-10-07T10:33:36Z"
    }
  ]
}

Response Fields

Field	Type	Description
`date`	String	Date and time when the transaction was recorded.
`txn_type`	String	Type of transaction, such as `utility_payment`, `collection`, or `payout`.
`type`	String	Indicates whether the transaction is a `credit` or `debit`.
`amount`	Number	Amount involved in the transaction.
`currency`	String	Currency of the transaction.
`txn_ref`	String	Unique reference identifying the transaction.
`available_balance_before`	Number	Available wallet balance before the transaction.
`available_balance_after`	Number	Available wallet balance after the transaction.
`ledger_balance_before`	Number	Ledger balance before the transaction.
`ledger_balance_after`	Number	Ledger balance after the transaction.
`status`	String	Current status of the transaction, such as `instant` or `settled`.
`settle_at`	String	Date and time when the transaction was settled. Returned when applicable.

Updated 14 days ago

Did this page help you?