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

# Create Refund

> Initiate an automated full or partial refund to the customer's bank account

## Request Body

<ParamField body="reference" type="string" required>
  The transaction reference of the original successful payment to refund.
</ParamField>

<ParamField body="amount" type="integer">
  Amount in **Kobo** to refund. If omitted, the full transaction amount is refunded.
</ParamField>

<ParamField body="reason" type="string">
  Merchant reason for issuing the refund (e.g. `Item out of stock`).
</ParamField>

## Response

<ResponseField name="status" type="string">
  Returns `success`.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="refundReference" type="string">
      Unique refund reference.
    </ResponseField>

    <ResponseField name="status" type="string">
      `PROCESSED` or `PENDING`.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Refunded amount in Kobo.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.handle.ng/v1/refunds \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "reference": "ORD-1092",
      "amount": 1500000,
      "reason": "Customer requested cancellation"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Refund processed successfully",
    "data": {
      "refundReference": "REF-89102-ORD-1092",
      "amount": 1500000,
      "currency": "NGN",
      "status": "PROCESSED",
      "refundedAt": "2026-09-21T08:35:00Z"
    }
  }
  ```
</ResponseExample>