Refunds
A refund gives back a Pix you received. It applies only to an incoming transaction (type: DEPOSIT) that is already settled (status: COMPLETED).
How it works
Send amount to give back part of the value, or omit the field to give back the full amount. The response returns immediately with the refund pending: confirmation is not synchronous.
A 200 response means the refund was accepted, not that the money is back. Wait for the webhook with status: REFUNDED before settling it on your side.
Always send clientReference
clientReference is the refund idempotency key. Without it, a retry after a timeout or network error gives the money back twice.
| Situation | What happens |
|---|---|
Same key, same amount | Returns the refund already created, no new one |
Same key, different amount | Rejected with PZC210 |
| No key | Every call creates a new refund |
Derive the key from your own order (refund-order-2026-001) and reuse the same value on the retry. For partial refunds, use one key per instalment.
Examples
Tracking the result
The refund fields come back in the callback and in the transaction lookup: refundStatus, refundAmount, refundEndToEndId, refundReason and refundedAt. The full reference is in Webhooks.