Skip to navigation

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

X-Acting-DocumentstringOptional

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.

X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Acting-IpstringOptional

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.

X-Acting-User-AgentstringOptional<=512 characters

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.

X-Acting-Device-IdstringOptional<=128 characters

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.

X-Acting-Session-IdstringOptional<=128 characters

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.

X-Acting-GeostringOptional

Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.

Request

This endpoint expects an object.
accountIdstringRequiredformat: "uuid"
Account identifier that received the original PIX.
originalEndToEndstringRequired

End-to-end identifier of the original PIX transaction to be refunded. Obtained from the receipt transaction via webhook or query.

amountdoubleRequired>=0.01

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

currencyenumRequiredDefaults to BRL

Currency code (only BRL supported).

Allowed values:
reasonenumRequired

Refund reason slug. Required. Mapped 1:1 to the settlement bank refund vocabulary, so any value outside this list is rejected with HTTP 400.

SlugQuando usar
user-requestedCliente final solicitou a devolução (caso mais comum).
transaction-errorErro genérico na transação (valor incorreto, dados inconsistentes).
unauthorized-transactionTransação não autorizada pelo titular.
fraudFraude comprovada/em investigação.
trade-disagreementDesacordo comercial (bem/serviço não entregue).
withdrawal-purchaseOperação envolvendo PIX Saque/Troco.
contractual-divergenceDivergência contratual entre as partes.
operational-errorErro operacional/processamento bancário.
duplicate-paymentPagamento duplicado.
metadatamap from strings to anyOptional
Additional metadata for internal tracking.

Response

Refund request accepted.
paymentIdstring
Internal payment intent identifier.
statusenum

Canonical status (same vocabulary as PIX out):

  • COMPLETED - refund settled (HTTP 200)
  • FAILED - rejected (HTTP 422)
  • TIMEOUT/PENDING/PROCESSING - not terminal yet (HTTP 202)
Allowed values:
transactionIdstringOptional
endToEndIdstringOptional

Refund D-code / E2E (present once registered).

errorCodestringOptional
errorReasonstringOptional
completedAtdatetimeOptional
idempotencyKeystringOptional
identifierstringOptional
workflowIdstringOptional

Errors

400
Bad Request Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error