Devolução

Devolve ao pagador, total ou parcialmente, um Pix recebido. O id é seu. Parciais são permitidas até a soma alcançar o valor original, em até 90 dias da liquidação.

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

Escopo: 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" }
}

Campo	Tipo	Obrigatório	Descrição
`valor`	string	sim	Valor a devolver, com duas casas.
`natureza`	string	não	`ORIGINAL`. Padrão.
`descricao`	string	não	Texto enviado com o estorno, até 140 caracteres, sem quebra de linha, tabulação ou outro caractere de controle. Nem toda conta repassa o texto ao pagador.

Campo do response	Tipo	Descrição
`status`	string	`EM_PROCESSAMENTO`, depois `DEVOLVIDO` ou `NAO_REALIZADO`.
`rtrId`	string	Identificador da devolução nesta API. Dependendo da conta, o comprovante do pagador traz outro; `GET /v2/ex/transacoes/mapear` acha a devolução pelos dois.

O desfecho chega pelo webhook devolucao.concluida ou devolucao.nao_realizada. Devolução é gratuita.

A devolução depende da conta que recebeu o Pix: GET /v2/ex/config traz capacidades.devolucao (para um Pix de sub-conta, ?subconta=). Onde ela é false, esta rota responde 503 capacidade_indisponivel, e o detail diz de qual conta e por quê.

Em algumas contas a devolução é só do valor inteiro do Pix. Nelas, um valor menor que o recebido responde 422 devolucao_so_integral, e nada é reservado.

Se a sua conta mudou de instituição depois de o Pix entrar, a devolução sai pela conta em que ele entrou. A chamada é a mesma. Se o saldo da conta foi transferido de uma instituição para a outra, a devolução do Pix de antes da transferência responde 422 devolucao_de_outra_conta, e quem a faz somos nós.

Consultar #

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

Escopo: 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 lista as devoluções que você pediu, com cursor. As que nós iniciamos não entram nela: chegam só pelo webhook devolucao.criada, com o motivo, e terminam em devolucao.concluida. Uma devolução nossa também pode terminar em devolucao.nao_realizada: o Pix não voltou ao pagador e foi creditado a você. O motivo dela repete o da devolucao.criada: é o motivo da recusa do Pix. O pix.creditado do mesmo Pix chega à parte, antes ou depois dela: a ordem entre os dois não é garantida.

Erros #

Status	`title`	Quando
400	`id_invalido`	`id` fora do formato.
400	`valor_invalido`	Valor fora do formato `"0.00"` ou não positivo.
400	`natureza_invalida`	`natureza` fora da lista.
400	`descricao_invalida`	`descricao` acima de 140 caracteres ou com caractere de controle (quebra de linha, tabulação).
409	`id_duplicado`	O mesmo `id` já existe com outro corpo.
422	`pix_nao_creditado`	O `endToEndId` não é de um Pix creditado nesta conta, ou o Pix está retido (`ex.situacaoFundos` `RETIDO`).
422	`devolucao_unica`	Nesta conta cada Pix aceita uma única devolução, e este já tem uma.
422	`devolucao_so_integral`	Nesta conta a devolução é só do valor inteiro do Pix, e o `valor` pedido é menor.
422	`devolucao_de_outra_conta`	O Pix entrou antes de o saldo da sua conta ser transferido de instituição. A devolução dele é feita por nós: fale com o suporte.
422	`devolucao_excede_recebido`	A soma das devoluções passaria do valor recebido.
422	`devolucao_prazo_excedido`	Passaram 90 dias da liquidação.
422	`saldo_insuficiente`	O disponível não cobre o valor.
503	`capacidade_indisponivel`	A conta não tem `capacidades.devolucao`.