CleonPay
Documentation Get in touch

API: Refunds

Return money to a customer, in full or in part, where the scheme allows it.

On this page

POST Create a refund /v1/refunds GET Retrieve a refund /v1/refunds/{id} GET List refunds /v1/refunds

Create a refund

POST /v1/refunds

Refunds a settled payment. Omit the amount to return the full remaining balance. Several partial refunds are allowed until the original amount is exhausted.

Send an Idempotency-Key header. Retrying with the same key returns the original result rather than creating a second one. See idempotency.

Body parameters

FieldTypeDescription
payment_id
required		 string The payment to refund. It must be settled.
amount integer Minor units. Omit for the full remaining balance. Cannot exceed it.
reason string Up to 500 characters, kept for your own reporting.

Request

curl https://api.cleonpay.com/v1/refunds \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: refund-order-1001-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "3743881d-0fce-416c-b3de-8bc3f5d414b1",
    "amount": 500,
    "reason": "One item returned"
  }'

Response

{
  "id": "b1c8b0a2-2f19-4a2e-9d51-6e9f3a1c7d40",
  "object": "refund",
  "payment_id": "3743881d-0fce-416c-b3de-8bc3f5d414b1",
  "amount": 500,
  "currency": "EUR",
  "status": "processing",
  "reason": "One item returned",
  "failure": null,
  "settled_at": null,
  "created_at": "2026-08-22T09: 04: 11.002Z"
}

Not every method can be refunded. Multibanco has no refund mechanism at all, and Przelewy24 stops at 90 days. The API refuses before the bank does, with refund_not_supported or refund_window_expired. More on refunds.

Retrieve a refund

GET /v1/refunds/{id}

Returns one refund and its current status.

Response

{
  "id": "b1c8b0a2-2f19-4a2e-9d51-6e9f3a1c7d40",
  "object": "refund",
  "status": "settled",
  "amount": 500,
  "currency": "EUR",
  "settled_at": "2026-08-23T02: 10: 44.771Z"
}

List refunds

GET /v1/refunds

Every refund on the account, newest first.

Query parameters

FieldTypeDescription
limit integer Between 1 and 100. Defaults to 25.

Response

{
  "object": "list",
  "data": [ { "id": "b1c8b0a2-...", "object": "refund", "status": "settled" } ]
}

On every request

HeaderDescription
Authorization Bearer <api key>. The key decides whether you are in sandbox or live; the host is the same either way.
Content-Type application/json on every request with a body.
Idempotency-Key On every creating request. Up to 255 characters, unique per operation, valid for 24 hours.

Errors follow one shape across every endpoint, described in errors.

PreviousAPI: Payments NextAPI: Payouts