API BaaSPix

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

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

reasonenumRequired

Refund reason slug. Required. Mapped 1:1 to the partner bank (MT 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)
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