Query Refund Status, History, and Counts by Status

After initializing a refund, use the endpoints on this page to track its progress and reconcile your refund history. All endpoints require standard merchant authentication headers. Headers

Header	Value
`X-Key-Id`	Your merchant key ID
`X-Timestamp`	Unix timestamp of the request
`X-Signature`	HMAC request signature

Get a single refund

Returns the current state and details of one refund by its unique reference.

GET https://sandbox.lyseis-pay.com/refunds/{refund_reference}

Path parameters

string

required

The unique refund reference assigned when the refund was initialized.

Example response

{
  "status": "success",
  "data": {
    "refund_reference": "refund_12345",
    "payment_reference": "order_12345",
    "currency": "NGN",
    "amount": 500.00,
    "reason": "Customer requested a partial refund",
    "refund_status": "processing",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:30Z"
  }
}

Get refunds for a payment

Returns all refunds associated with a single original payment. Useful when multiple partial refunds have been issued against the same transaction.

GET https://sandbox.lyseis-pay.com/refunds/transactions/{payment_reference}

Path parameters

string

required

The original payment reference for which you want to retrieve all associated refunds.

Example response

{
  "status": "success",
  "data": [
    {
      "refund_reference": "refund_12345",
      "payment_reference": "order_12345",
      "currency": "NGN",
      "amount": 500.00,
      "refund_status": "success",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "refund_reference": "refund_12346",
      "payment_reference": "order_12345",
      "currency": "NGN",
      "amount": 250.00,
      "refund_status": "processing",
      "created_at": "2026-01-16T09:00:00Z"
    }
  ]
}

List all merchant refunds

Returns a paginated list of all refunds on your merchant account. Supports filtering by status, payment reference, and date range.

GET https://sandbox.lyseis-pay.com/merchants/refunds

Query parameters

string

Filter results by refund status. Accepted values: processing, success, failed.

string

Filter results to refunds associated with a specific original payment reference.

string

Return only refunds created on or after this date. Format: YYYY-MM-DD.

string

Return only refunds created on or before this date. Format: YYYY-MM-DD.

integer

default:"1"

Page number to retrieve. Defaults to 1.

integer

default:"10"

Number of records per page. Defaults to 10. Maximum is 100.

Example request

GET https://sandbox.lyseis-pay.com/merchants/refunds?status=success&start_date=2026-01-01&end_date=2026-01-31&page=1&page_size=25

Example response

{
  "status": "success",
  "data": {
    "total": 42,
    "page": 1,
    "pageSize": 25,
    "records": [
      {
        "refund_reference": "refund_12345",
        "payment_reference": "order_12345",
        "currency": "NGN",
        "amount": 500.00,
        "reason": "Customer requested a partial refund",
        "refund_status": "success",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:05:00Z"
      }
    ]
  }
}

Refund counts by status

Returns a breakdown of your refund counts grouped by their current status. Useful for dashboard summaries and reconciliation.

GET https://sandbox.lyseis-pay.com/refunds/count-by-status

Example response

{
  "status": "success",
  "data": {
    "processing": 3,
    "success": 87,
    "failed": 5
  }
}

Refund statuses

Status	Description
`processing`	The refund has been accepted and queued. Bank processing is underway; the outcome is not yet final.
`success`	The refund was processed successfully and funds have been returned to the customer or destination account.
`failed`	The refund could not be completed. Review the refund details and contact support if the issue persists.

Payments

Virtual Accounts

Direct Debits

Refunds

Transfers

Banks

Query Refund Status, History, and Counts by Status

Get a single refund

Path parameters

Example response

Get refunds for a payment

Path parameters

Example response

List all merchant refunds

Query parameters

Example request

Example response

Refund counts by status

Example response

Refund statuses

​Get a single refund

​Path parameters

​Example response

​Get refunds for a payment

​Path parameters

​Example response

​List all merchant refunds

​Query parameters

​Example request

​Example response

​Refund counts by status

​Example response

​Refund statuses

Get a single refund

Path parameters

Example response

Get refunds for a payment

Path parameters

Example response

List all merchant refunds

Query parameters

Example request

Example response

Refund counts by status

Example response

Refund statuses