Transaction History

The Transaction History endpoint allows merchants to retrieve a filtered list of past transactions based on date range, status, or reference. This is useful for reconciliation, reporting, and auditing purposes.

Endpoint

GET transaction/history?startDate={`{startDate}`}&endDate={`{endDate}`}&status={`{status}`}&reference={`{reference}`}&page={`{page}`}&size={`{size}`}

Headers

Key	Value	Required	Description
`Authorization`	`{{private_key}}`	Yes	Merchant's private key for authentication.

Query Parameters

Parameter	Type	Description	Default
`startDate`	Unix Timestamp	Filters transactions from this timestamp (inclusive).	24 hours ago
`endDate`	Unix Timestamp	Filters transactions up to this timestamp (inclusive).	Current time
`status`	Integer	Filters by transaction status (e.g., `6` = Refunded).	All statuses
`reference`	String	Filters by `transactionReference` or `merchantRef`.
`page`	Integer	Page number for pagination (minimum 1)	1
`size`	Integer	Items per page (maximum 100)	25

Sample Response

{
  "status": 200,
  "message": "Request successfully processed",
  "data": {
    "content": [
      {
        "transactionReference": "XLs8M1jl0I2dzPYmmzfE",
        "reference": "9e165283-00ac-48e7-813f-e559324e5502",
        "grossAmount": 150.00,
        "requestedAmount": 150.00,
        "transactionFee": 2.25,
        "settlementAmount": 147.75,
        "customerId": "[email protected]",
        "currencyCode": "NGN",
        "createdDate": "2025-03-30T17:01:46.827105",
        "status": 1,
        "errorCode": "0"
      },
      {
        "transactionReference": "MX9KiGstDRW_tpsaB9zp",
        "reference": "bf925674-4430-4374-9e04-4918332ca0e7",
        "grossAmount": 2.00,
        "requestedAmount": 2.00,
        "transactionFee": 0.00,
        "settlementAmount": 2.00,
        "customerId": "[email protected]",
        "currencyCode": "USD",
        "createdDate": "2025-03-30T14:27:20.240288",
        "status": 1,
        "errorCode": "0"
      }
    ],
    "number": 0,
    "size": 25,
    "totalElements": 2,
    "totalPages": 1,
    "last": true,
    "first": true
  },
  "errors": []
}

Response Fields

Field	Type	Description
`transactionReference`	`string`	Unique reference for the refund transaction.
`reference`	`decimal`	Merchant’s original order reference.
`grossAmount`	`decimal`	Original transaction amount..
`requestedAmount`	`decimal`	Amount requested by the merchant
`transactionFee`	`decimal`	Processing/Transaction fee deducted
`settledAmount`	`decimal`	Net amount after fees
`customerId`	`string`	Unique customer identifier (e.g, email address)
`currencyCode`	`string`	Currency code (e.g., `NGN/ USD`).
`createdDate`	`string`	Timestamp when the transaction was created.
`status`	`integer`	Refund status code (see Status Codes).
`errorCode`	`string`	Error code (0 = success)