# Create a refund

> Refund an approved payment in full or in part.

`POST https://api.camelpayment.com/v1/payments/{payment_id}/refunds`

The payment must be approved or partially_refunded. The refund uses the payment currency. Pending refunds count against the refundable balance, so two refunds cannot exceed the payment together.

## Path parameters

- `payment_id` (string, required): The payment id, starting with pay_.

## Headers

- `Idempotency-Key` (string, required): A unique key for this operation, up to 255 characters. Retrying with the same key and body returns the original response. See Idempotency.

## Body parameters

- `amount` (integer): Minor units, greater than 0. Leave it out to refund the whole remaining balance.

## Request

**cURL**

```bash
curl -X POST https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: refund-1524-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Idempotency-Key': 'refund-1524-1',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 500000
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
        "Idempotency-Key": "refund-1524-1",
    },
    json={
        "amount": 500000
    },
)
data = response.json()
```

## Response

**201**

```json
{
  "id": "ref_01JBX8A1B2C3D4E5F6G7H8J9KM",
  "payment_id": "pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
  "provider_refund_id": "987654321",
  "amount": 500000,
  "currency": "ARS",
  "status": "approved",
  "provider_status": "approved",
  "failure_code": null,
  "created_at": "2026-11-12T16:10:00Z",
  "updated_at": "2026-11-12T16:10:02Z"
}
```

## Errors

| Status | When |
| --- | --- |
| `202` | The provider did not give a definitive answer (a timeout, for example). The resource is returned with status unknown and Camel reconciles it. Do not create it again. |
| `401` | The API key is missing, malformed, or revoked. |
| `404` | No payment with this id in this environment. |
| `409` | The payment is not refundable in its state, the amount exceeds the remaining balance, or the connection is unavailable. |
| `409` | The Idempotency-Key was used with a different body, or the first request is still running. |
| `422` | The body is invalid. |
| `429` | Too many requests. Wait for Retry-After seconds. |
| `502` | The provider returned an error. The body is still the resource, with status failed. |
