## How it works

A refund returns already captured money through the original connector. Releasing an uncaptured authorization uses payment cancellation instead.

## Implementation

Create a refund with payment_id and, for a partial refund, amount in minor units. Store your own refund_id to reconcile uncertain retries; do not assume every endpoint supports an idempotency header. Product line credits associate the refund with catalog lines for accounting. Inspect pending, review, succeeded or failed status and wait for the event or retrieved result. A submitted request alone does not prove that the buyer has received funds.

## Create a refund

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `payment_id` | string | Yes | The payment. |
| `amount` | integer | No | Minor units. Default: the full captured amount. |
| `refund_id` | string | No | Your ID, up to 64 characters. Default: generated `ref_…`. |
| `reason` | string | No | Free text, up to 255 characters. |
| `metadata` | object | No | Your keys. |
| `line_credits` | array | No | Lines to credit; see [below](#credit-product-lines). |

## Track the refund

| Status | Meaning |
| --- | --- |
| `pending` | Sent; no result yet. |
| `succeeded` | Completed. |
| `failed` | Refused or failed by the processor. |
| `review` | Held for manual review. |

## Related guides

- [Accept payments](/docs/payment-api/accept-payments/)
- [Products and line items](/docs/payment-api/products/)
- [Webhook events](/docs/payment-api/webhooks/)
- [Invoices & credit notes](/docs/payment-api/invoices/)

## Request examples

```bash
curl -X POST https://api.spicepay.net/refunds \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_xxxxx",
    "refund_id": "ref_order_2042_1",
    "amount": 1000,
    "reason": "requested_by_customer"
  }'
```

```bash
curl https://api.spicepay.net/payments/pay_xxxxx/lines \
  -H 'api-key: YOUR_API_KEY'
```

```bash
curl -X POST https://api.spicepay.net/refunds \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_xxxxx",
    "amount": 2500,
    "line_credits": [
      { "line_id": "ppl_xxxxx", "quantity": 1, "amount": 2000, "tax_amount": 319 }
    ]
  }'
```

## Credit product lines

Retrieve the payment lines, then associate each credit with its `line_id`. Supply the quantity, credited amount and tax amount that match the intended correction. Keep line totals consistent with the refund amount and the remaining refundable balance. Use the line-credit request shown above when issuing a partial product refund.