> ## 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.

# Initialize and Track Refunds for Paylink Payments

> Learn how to initialize full or partial refunds, track refund status, query refund history, and handle async completion with Paylink.

Paylink lets you refund any successful payment, either in full or partially. Refunds are processed asynchronously — after you initialize a refund, poll the status endpoint or listen for a webhook event to confirm completion.

## Initialize a Refund

Send a `POST` request to `/refunds/initialize` to start a refund:

```json Request theme={null}
{
  "payment_reference": "order_12345",
  "refund_reference": "refund_12345",
  "currency": "NGN",
  "amount": 500.00,
  "reason": "Customer requested a partial refund",
  "account_number": "0123456789",
  "bank_code": "058"
}
```

| Field               | Required    | Description                                                                                    |
| ------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `payment_reference` | ✅           | Reference of the original payment to refund                                                    |
| `refund_reference`  | ✅           | Your unique identifier for this refund request                                                 |
| `currency`          | ✅           | Currency of the refund, e.g. `NGN`                                                             |
| `amount`            | ✅           | Amount to refund. Must not exceed the original payment amount                                  |
| `reason`            | Optional    | Short description of why the refund is being issued                                            |
| `account_number`    | Conditional | Destination bank account number. Required when the customer's card cannot be credited directly |
| `bank_code`         | Conditional | Three-digit bank code for the destination account. Required when `account_number` is provided  |

### Full vs. Partial Refunds

The `amount` field controls whether a refund is full or partial:

* **Full refund** — set `amount` to the exact amount of the original payment.
* **Partial refund** — set `amount` to any value less than the original payment amount.

You can issue multiple partial refunds against a single payment as long as their total does not exceed the original charge.

<Note>
  `account_number` and `bank_code` may be required depending on the original payment method. If the customer paid by card and their card cannot be credited directly, you must provide a destination bank account.
</Note>

A successful response confirms the refund has been queued:

```json Response theme={null}
{
  "status": "processing",
  "message": "Refund has been queued for processing",
  "refund_reference": "refund_12345",
  "payment_reference": "order_12345"
}
```

<Warning>
  Each `refund_reference` must be unique across all your refund requests. Submitting a duplicate `refund_reference` returns a `409` error. Generate a new reference for every refund attempt, even if you are retrying a failed one.
</Warning>

## Track Refund Status

### Get a Single Refund

Call `GET /refunds/{refund_reference}` to fetch the current status of a specific refund:

```http Request theme={null}
GET /refunds/refund_12345
```

```json Response theme={null}
{
  "refund_reference": "refund_12345",
  "payment_reference": "order_12345",
  "amount": 500.00,
  "currency": "NGN",
  "status": "success",
  "reason": "Customer requested a partial refund",
  "created_at": "2026-01-20T14:22:00Z"
}
```

### Refund Statuses

| Status       | Meaning                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `processing` | The refund has been queued and is being processed by the banking network |
| `success`    | Funds have been returned to the customer                                 |
| `failed`     | The refund could not be completed. Contact support if this persists      |

<Tip>
  Rather than polling repeatedly, set up a webhook listener to receive a notification when the refund status changes to `success` or `failed`.
</Tip>

## List All Refunds for a Payment

To see every refund associated with a specific original payment, call `GET /refunds/transactions/{payment_reference}`:

```http Request theme={null}
GET /refunds/transactions/order_12345
```

This is useful when a payment has received multiple partial refunds and you need to reconcile the total amount refunded.

## Query Refund History

Retrieve a paginated list of all refunds across your merchant account at `GET /merchants/refunds`:

```http Example request theme={null}
GET /merchants/refunds?status=processing&start_date=2026-01-01&end_date=2026-01-31&page=1&page_size=25
```

| Parameter           | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `status`            | Filter by refund status: `processing`, `success`, or `failed` |
| `payment_reference` | Filter refunds tied to a specific original payment            |
| `start_date`        | Earliest refund date (ISO 8601)                               |
| `end_date`          | Latest refund date (ISO 8601)                                 |
| `page`              | Page number (default `1`)                                     |
| `page_size`         | Results per page (default `10`, max `100`)                    |

## Get Refund Counts by Status

For a quick summary of your refund activity, call `GET /refunds/count-by-status`:

```http Request theme={null}
GET /refunds/count-by-status
```

```json Response theme={null}
{
  "processing": 4,
  "success": 118,
  "failed": 2
}
```

This endpoint is handy for dashboard widgets or monitoring alerts — for example, alerting your team when the `failed` count spikes unexpectedly.