Request Pix outbound refund
Requests a refund (reversal) of a previously received PIX.
Important: Only received PIX transactions can be refunded. The refund
is identified by the originalEndToEnd from the original transaction.
Full or partial: amount may equal the original PIX amount (full
refund) or be smaller (partial refund). Above the original, the API
returns 400 refund_amount_exceeded and does not start the refund.
The same PIX can be refunded in more than one installment, each with its
own Idempotency-Key and identifier — reusing either returns the
previous refund instead of starting a new one. The refundable balance is
tracked by the banking partner: an installment beyond it comes back as
refund_amount_exceeded.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Client-generated idempotency token.
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.
Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).
Real IP of the end user, for integrator credentials calling on their behalf. This is the IP evaluated against cashoutSourceIps — without it the check would see your server’s IP. Ignored for delegated credentials, where the connection IP is already the right one.
Optional user-agent of the end user’s browser or app, for integrator credentials calling on their behalf. Feeds risk analysis only: an invalid or oversized value is dropped and the payment still proceeds. Ignored for delegated credentials.
Optional device fingerprint or identifier from the integrator’s own system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional session id of the end user in the integrator’s system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.
Request
End-to-end identifier of the original PIX transaction to be refunded. Obtained from the receipt transaction via webhook or query.
Amount to be refunded in BRL. Max 2 decimal places (e.g., 150.75 for R$150,75).
Equal to the original PIX amount for a full refund, or smaller for a partial
refund. It cannot exceed the original amount (400 refund_amount_exceeded).
Currency code (only BRL supported).
Refund reason slug. Required. Mapped 1:1 to the settlement bank refund vocabulary, so any value outside this list is rejected with HTTP 400.
Response
Canonical status (same vocabulary as PIX out):
COMPLETED- refund settled (HTTP 200)FAILED- rejected (HTTP 422)TIMEOUT/PENDING/PROCESSING- not terminal yet (HTTP 202)
Refund D-code / E2E (present once registered).