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"
}
→ 201
{
  "id": "DEV01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000001",
  "rtrId": "D12345678202609181200000000000001",
  "valor": "50.00",
  "natureza": "ORIGINAL",
  "status": "EM_PROCESSAMENTO",
  "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.

Campo do response	Tipo	Descrição
`status`	string	`EM_PROCESSAMENTO`, depois `DEVOLVIDO` ou `NAO_REALIZADO`.
`rtrId`	string	Identificador da devolução na liquidação.

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

A devolução depende da conta: GET /v2/ex/config traz capacidades.devolucao. Onde ela é false, esta rota responde 503 capacidade_indisponivel, e o detail diz de qual conta e por quê.

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 da conta, com cursor. Inclui as que nós iniciamos: elas chegam pelo webhook devolucao.criada com o motivo.

Erros #

Status	`title`	Quando
400	`id_invalido`	`id` fora do formato.
400	`valor_invalido`	Valor fora do formato `"0.00"` ou não positivo.
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.
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`.