> ## 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 a Refund Request — POST /refunds/initialize

> Issue a full or partial refund against a completed payment. Refunds are processed asynchronously; poll the status endpoint to track the final outcome.

Use this endpoint to initiate a refund against a completed payment. You can issue a full refund for the original amount or a partial refund by specifying a lesser `amount`. Refund processing is asynchronous; the API responds immediately with a confirmation that the refund has been queued, and the final outcome is available via the status endpoint or a webhook notification.

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

**Headers**

| Header         | Value                         |
| -------------- | ----------------------------- |
| `X-Key-Id`     | Your merchant key ID          |
| `X-Timestamp`  | Unix timestamp of the request |
| `X-Signature`  | HMAC request signature        |
| `Content-Type` | `application/json`            |

## Request body

<ParamField body="payment_reference" type="string" required>
  The unique reference of the original payment you want to refund. This must correspond to a completed transaction on your merchant account.
</ParamField>

<ParamField body="refund_reference" type="string" required>
  A unique reference you assign to this refund request. Used to query refund status and to identify the refund in webhook events. Must be unique — submitting a duplicate `refund_reference` returns `409 Refund already exists`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code for the refund (e.g. `NGN`). Must match the currency of the original payment.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to refund. To issue a **partial refund**, specify an amount less than the original payment amount. To issue a **full refund**, match the original payment amount exactly.
</ParamField>

<ParamField body="reason" type="string">
  A human-readable reason for the refund. Stored for your records and may appear in customer notifications.
</ParamField>

<ParamField body="account_number" type="string">
  Destination bank account number for the refund. Required when the refund is to be sent to a specific account rather than reversed to the original payment method.
</ParamField>

<ParamField body="bank_code" type="string">
  Bank code for the destination account. Required when `account_number` is provided. Use `GET /banks` to retrieve the list of supported bank codes.
</ParamField>

## Example request

```json 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"
}
```

## Example response

```json theme={null}
{
  "status": "success",
  "message": "Refund initialized successfully",
  "refund_reference": "refund_12345",
  "payment_reference": "order_12345"
}
```

### Response fields

<ResponseField name="status" type="string">
  Indicates whether the request was accepted. A value of `success` means the refund has been queued for processing.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable description of the result.
</ResponseField>

<ResponseField name="refund_reference" type="string">
  The unique reference you supplied for this refund. Use it to poll for the final status.
</ResponseField>

<ResponseField name="payment_reference" type="string">
  The original payment reference the refund was raised against.
</ResponseField>

## Checking refund status

Refund processing is **asynchronous**. The response above confirms only that the refund has been accepted and queued. Poll the status endpoint to determine the final outcome:

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

See [Query Refunds](/api-reference/refunds/query) for full details on status polling and available statuses.

## Error reference

| HTTP status | Error message         | Resolution                                                                                                          |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `409`       | Refund already exists | The `refund_reference` you provided has already been used. Generate a new unique reference for each refund request. |