Refund

Returns a received Pix to the payer, in full or in part. The id is yours. Partial refunds are allowed until their sum reaches the original amount, within 90 days of settlement.

PUT /v2/pix/{e2eId}/devolucao/{id}

Scope: pix.write.

PUT /v2/pix/E12345678202609181200000000000001/devolucao/DEV01J1ZK7M9QW3ERT5TY6UI8O
{
  "valor": "50.00",
  "descricao": "Pedido 4471 cancelado"
}
→ 201
{
  "id": "DEV01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000001",
  "rtrId": "D12345678202609181200000000000001",
  "valor": "50.00",
  "natureza": "ORIGINAL",
  "status": "EM_PROCESSAMENTO",
  "descricao": "Pedido 4471 cancelado",
  "horario": { "solicitacao": "2026-09-18T12:00:00Z" }
}

Field	Type	Required	Description
`valor`	string	yes	Amount to refund, with two decimal places.
`natureza`	string	no	`ORIGINAL`. Default.
`descricao`	string	no	Text sent with the refund, up to 140 characters, without line breaks, tabs or other control characters. Not every account passes the text on to the payer.

Response field	Type	Description
`status`	string	`EM_PROCESSAMENTO`, then `DEVOLVIDO` or `NAO_REALIZADO`.
`rtrId`	string	Identifier of the refund in this API. Depending on the account, the receipt of the payer carries a different one; `GET /v2/ex/transacoes/mapear` finds the refund by either.

The outcome arrives through the webhook devolucao.concluida or devolucao.nao_realizada. Refunds are free of charge.

Refunds depend on the account that received the Pix: GET /v2/ex/config carries capacidades.devolucao (for a Pix received by a sub-account, ?subconta=). Where it is false, this route responds 503 capacidade_indisponivel, and the detail says which account and why.

On some accounts a refund can only be for the whole amount of the Pix. On those accounts, a valor lower than the amount received responds 422 devolucao_so_integral, and nothing is reserved.

If your account changed institutions after the Pix came in, the refund goes out through the account where the Pix came in. The call is the same. If the balance of the account was transferred from one institution to the other, the refund of a Pix from before the transfer responds 422 devolucao_de_outra_conta, and we make that refund.

Get #

GET /v2/pix/{e2eId}/devolucao/{id}

Scope: pix.read.

GET /v2/pix/E12345678202609181200000000000001/devolucao/DEV01J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "id": "DEV01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000001",
  "rtrId": "D12345678202609181200000000000001",
  "valor": "50.00",
  "natureza": "ORIGINAL",
  "status": "EM_PROCESSAMENTO",
  "horario": { "solicitacao": "2026-09-18T12:00:00Z" }
}

GET /v2/ex/devolucoes lists the refunds you requested, with a cursor. The ones we started are not in it: they only arrive through the webhook devolucao.criada, with the motivo, and end in devolucao.concluida. A refund of ours can also end in devolucao.nao_realizada: the Pix did not go back to the payer and was credited to you. Its motivo repeats the one in devolucao.criada: it is the reason the Pix was refused. The pix.creditado of the same Pix arrives separately, before or after it: the order between the two is not guaranteed.

Errors #

Status	`title`	When
400	`id_invalido`	`id` outside the format.
400	`valor_invalido`	Amount outside the format `"0.00"` or not positive.
400	`natureza_invalida`	`natureza` outside the list.
400	`descricao_invalida`	`descricao` longer than 140 characters or with a control character (line break, tab).
409	`id_duplicado`	The same `id` already exists with a different body.
422	`pix_nao_creditado`	The `endToEndId` is not of a Pix credited to this account, or the Pix is on hold (`ex.situacaoFundos` `RETIDO`).
422	`devolucao_unica`	On this account each Pix accepts a single refund, and this one already has one.
422	`devolucao_so_integral`	On this account a refund can only be for the whole amount of the Pix, and the requested `valor` is lower.
422	`devolucao_de_outra_conta`	The Pix came in before the balance of your account was transferred to another institution. Its refund is made by us: talk to support.
422	`devolucao_excede_recebido`	The sum of the refunds would exceed the amount received.
422	`devolucao_prazo_excedido`	90 days have passed since settlement.
422	`saldo_insuficiente`	The available balance does not cover the amount.
503	`capacidade_indisponivel`	The account does not have `capacidades.devolucao`.