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

# Create Refund

> Refund a payment (full or partial)

Refund a completed payment, either fully or partially. The merchant wallet is debited and the user wallet is credited.

## Endpoint

`POST https://quickei.io/pay/sandbox/api/v1/refunds`

## Parameters

<ParamField body="transaction_id" type="string" required>
  The original payment transaction ID (e.g. `TRX-98765`).
</ParamField>

<ParamField body="amount" type="decimal">
  Amount to refund. Omit for a full refund. Must be greater than 0 and not exceed the remaining refundable amount.
</ParamField>

<ParamField body="reason" type="string">
  Reason for the refund (max 500 chars).
</ParamField>

<ParamField body="reference" type="string">
  Your internal reference for this refund (max 255 chars).
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key to prevent duplicate refunds (max 64 chars).
</ParamField>

> **Partial refunds:** You can issue multiple partial refunds against the same transaction until the total refunded amount equals the original payment amount.

## Example Request

```bash theme={null}
curl -X POST https://quickei.io/pay/sandbox/api/v1/refunds \
  -H "Authorization: Basic {base64_credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TRX-98765",
    "amount": 10.00,
    "reason": "Item returned",
    "reference": "RFD-2024-001",
    "idempotency_key": "idem_rfd_abc123"
  }'
```

## Success Response `200`

```json theme={null}
{
  "message": {
    "success": ["Refund created successfully"]
  },
  "data": {
    "refund_id": "RF-20240115-X7Y8Z9",
    "transaction_id": "TRX-98765",
    "amount": "10.00 EUR",
    "raw_amount": 10.00,
    "currency": "EUR",
    "status": "completed",
    "reason": "Item returned",
    "reference": "RFD-2024-001",
    "created_at": "2024-01-15T16:30:00+00:00"
  }
}
```

## Response Fields

| Field            | Description                           |
| ---------------- | ------------------------------------- |
| `refund_id`      | Unique refund identifier (RF prefix)  |
| `transaction_id` | Original payment transaction ID       |
| `amount`         | Formatted refund amount with currency |
| `raw_amount`     | Numeric refund amount                 |
| `currency`       | ISO 4217 currency code                |
| `status`         | `pending`, `completed`, or `failed`   |
| `reason`         | Refund reason (if provided)           |
| `reference`      | Your internal reference (if provided) |
| `created_at`     | ISO 8601 timestamp                    |

## Error Responses

### `404` Transaction not found

```json theme={null}
{
  "message": {
    "error": ["Transaction not found"]
  }
}
```

### `422` Refund exceeds original amount

```json theme={null}
{
  "message": {
    "error": ["Refund amount exceeds the remaining refundable amount"]
  }
}
```

### `422` Transaction not refundable

```json theme={null}
{
  "message": {
    "error": ["Transaction is not eligible for refund"]
  }
}
```