> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyseis-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Refund Status, History, and Counts by Status

> Retrieve the status of a single refund, list all refunds for a payment, paginate through your full refund history, and get counts broken down 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.

```http theme={null}
GET https://sandbox.lyseis-pay.com/refunds/{refund_reference}
```

### Path parameters

<ParamField path="refund_reference" type="string" required>
  The unique refund reference assigned when the refund was initialized.
</ParamField>

### Example response

```json theme={null}
{
  "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.

```http theme={null}
GET https://sandbox.lyseis-pay.com/refunds/transactions/{payment_reference}
```

### Path parameters

<ParamField path="payment_reference" type="string" required>
  The original payment reference for which you want to retrieve all associated refunds.
</ParamField>

### Example response

```json theme={null}
{
  "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.

```http theme={null}
GET https://sandbox.lyseis-pay.com/merchants/refunds
```

### Query parameters

<ParamField query="status" type="string">
  Filter results by refund status. Accepted values: `processing`, `success`, `failed`.
</ParamField>

<ParamField query="payment_reference" type="string">
  Filter results to refunds associated with a specific original payment reference.
</ParamField>

<ParamField query="start_date" type="string">
  Return only refunds created on or after this date. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="end_date" type="string">
  Return only refunds created on or before this date. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Number of records per page. Defaults to `10`. Maximum is `100`.
</ParamField>

### Example request

```http theme={null}
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

```json theme={null}
{
  "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.

```http theme={null}
GET https://sandbox.lyseis-pay.com/refunds/count-by-status
```

### Example response

```json theme={null}
{
  "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.    |