Refunds

Full or partial refund of a paid charge.

Refund is the public refund object. Create a refund on a `paid` or `partially_refunded` charge to return captured funds.

Rules

Omit amount_cents to refund the remaining balance. Send a partial amount for multiple refunds until the balance reaches zero. The parent charge moves to refunded or partially_refunded per contract.

Refund status

processing

Refund was created and sent to the acquirer.

succeeded

Refund confirmed; the charge may move to refunded.

failed

Acquirer rejected the refund; the charge stays paid.

POST/charges/{id}/refund

Refund charge

Refunds a paid or partially refunded charge. Omit `amount_cents` to refund the remaining balance.

Auth: Bearer API keyrefunds:createIdempotency-Key supported

Headers

Field	Type	Description
`Idempotency-Key`	string	Recommended for refund retries.

Parameters and body

Field	Type	Description
`id`required	path string	Paid charge id with `ch_` prefix.
`amount_cents`	integer	Partial refund amount in cents. Omit for a full refund of the remaining balance.
`reason`	string	Optional refund reason, up to 120 characters.

Response fields

Field	Type	Description
`id`	string	`rf_` public id.
`object`	string	`refund`.
`status`	string	`succeeded` or `failed` after provider processing.
`charge_id`	string	Parent charge public id.
`amount_cents`	integer	Refunded amount in cents.
`provider_reference`	string	Acquirer refund reference when available.
`request_id`	string	Request trace id.

Request examples

curl -X POST https://bunne.com.br/api/v1/charges/ch_xxx/refund \  -H "Authorization: Bearer sk_test_xxx" \  -H "Idempotency-Key: order_123_refund" \  -H "Content-Type: application/json" \  -d '{  "reason": "requested_by_customer"}'

Response

{  "id": "rf_xxx",  "object": "refund",  "status": "succeeded",  "charge_id": "ch_xxx",  "amount_cents": 10990,  "currency": "BRL",  "reason": "requested_by_customer",  "provider_reference": "re_provider_abc123",  "succeeded_at": "2026-06-25T13:00:05.000Z",  "created_at": "2026-06-25T13:00:00.000Z",  "updated_at": "2026-06-25T13:00:05.000Z",  "request_id": "req_xxx"}

Related events

Field	Type	Description
`refund.created`	webhook	A refund was requested and persisted.
`refund.succeeded`	webhook	A refund was confirmed by the acquirer.
`refund.failed`	webhook	A refund failed after acquirer processing.
`charge.refunded`	webhook	The parent charge refund state changed.

Common errors

Field	Type	Description
`charge_not_refundable`	422	Charge is not in a refundable state.
`amount_exceeds_charge`	422	Amount exceeds the remaining refundable balance.
`provider_unavailable`	502	Acquirer unavailable; retry later.