Docs
Search the docs
Find a page in the docs

API reference

Create a refund

Refund an approved payment in full or in part.

POST /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 -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
  }'

Response

201
{
  "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

StatusWhen
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.