# Refund a payment

> Refunds all or part of a paid payment.

Source: https://rais.app/docs/api/create-refund

`POST /v1/payments/{payment_id}/refunds`

Required scope: `refunds:write`.

Without `amount`, everything still refundable is refunded; a payment can be refunded several times, never beyond what was paid. The refund is performed with the payment gateway before the answer is returned: `succeeded` (201), or `pending` (202) if the gateway's answer was lost, in which case the amount stays reserved and you must look at the refund (`GET /refunds/{id}`) before trying again. A refusal by the bank answers `402 refund_declined`. A key can only refund payments of its own store and environment. Send an `Idempotency-Key` so that retrying can never refund twice.

## Request

### Headers

- `Idempotency-Key` (string, optional): A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Body

Optional, JSON.

- `amount` (integer, optional): How much to refund, as an INTEGER in centimes (at least 100 = 1 DA). Defaults to everything still refundable.
- `reason` (string, optional): Why you are refunding. For your records. At most 255 characters.

### Example request

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/refunds \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 150000,
  "reason": "Customer returned one item"
}'
```

## Response

### 201: The refund succeeded.

Returns the [Refund object](https://rais.app/docs/api/objects/refund.md).

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

### 202: The refund was sent but the gateway's answer was lost: `status` is `pending` and the amount is reserved.

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "pending",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_json` | The request body is not valid JSON. |
| 400 | `invalid_amount` | amount must be an integer number of centimes (500000 is 5,000.00 DA). |
| 400 | `amount_too_small` | The minimum amount is 50.00 DA (5000 centimes). |
| 400 | `refund_exceeds_balance` | The refund (500000 centimes) exceeds what can still be refunded (200000 centimes). |
| 400 | `insufficient_balance` | The store's balance is not sufficient to cover this refund and its fee. |
| 400 | `invalid_idempotency_key` | The Idempotency-Key header must be 1 to 255 printable ASCII characters. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 402 | `refund_declined` | The bank refused the refund. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 409 | `payment_not_refundable` | Cannot refund a payment with status 'pending'. |
| 409 | `idempotency_in_progress` | A request with this Idempotency-Key is still being processed. Retry in a moment. |
| 422 | `idempotency_key_reused` | This Idempotency-Key was already used with different request parameters. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |
| 503 | `gateway_unavailable` | The payment gateway is temporarily unavailable. Please try again later. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Refunds](https://rais.app/docs/refunds.md)
- [Idempotency and retries](https://rais.app/docs/idempotency.md)