Devolución

Devuelve al pagador, total o parcialmente, un Pix recibido. El id es suyo. Se permiten devoluciones parciales hasta que la suma alcance el valor original, en un plazo de hasta 90 días desde la liquidación.

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

Alcance: 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	Obligatorio	Descripción
`valor`	string	sí	Valor a devolver, con dos decimales.
`natureza`	string	no	`ORIGINAL`. Por defecto.
`descricao`	string	no	Texto enviado con el reembolso, hasta 140 caracteres, sin salto de línea, tabulación u otro carácter de control. No todas las cuentas transmiten el texto al pagador.

Campo del response	Tipo	Descripción
`status`	string	`EM_PROCESSAMENTO`, después `DEVOLVIDO` o `NAO_REALIZADO`.
`rtrId`	string	Identificador de la devolución en esta API. Según la cuenta, el comprobante del pagador trae otro; `GET /v2/ex/transacoes/mapear` encuentra la devolución por los dos.

El desenlace llega por el webhook devolucao.concluida o devolucao.nao_realizada. La devolución es gratuita.

La devolución depende de la cuenta que recibió el Pix: GET /v2/ex/config trae capacidades.devolucao (para un Pix de subcuenta, ?subconta=). Donde es false, esta ruta responde 503 capacidade_indisponivel, y el detail dice de qué cuenta y por qué.

En algunas cuentas la devolución es solo del valor completo del Pix. En ellas, un valor menor que el recibido responde 422 devolucao_so_integral, y no se reserva nada.

Si su cuenta cambió de institución después de que entró el Pix, la devolución sale por la cuenta en la que entró. La llamada es la misma. Si el saldo de la cuenta fue transferido de una institución a otra, la devolución del Pix anterior a la transferencia responde 422 devolucao_de_outra_conta, y quien la hace somos nosotros.

Consultar #

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

Alcance: 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 las devoluciones que usted solicitó, con cursor. Las que iniciamos nosotros no están en ella: llegan solo por el webhook devolucao.criada, con el motivo, y terminan en devolucao.concluida. Una devolución nuestra también puede terminar en devolucao.nao_realizada: el Pix no volvió al pagador y fue acreditado a usted. Su motivo repite el de devolucao.criada: es el motivo del rechazo del Pix. El pix.creditado del mismo Pix llega aparte, antes o después de ella: el orden entre los dos no está garantizado.

Errores #

Estado	`title`	Cuándo
400	`id_invalido`	`id` fuera del formato.
400	`valor_invalido`	Valor fuera del formato `"0.00"` o no positivo.
400	`natureza_invalida`	`natureza` fuera de la lista.
400	`descricao_invalida`	`descricao` de más de 140 caracteres o con carácter de control (salto de línea, tabulación).
409	`id_duplicado`	El mismo `id` ya existe con otro cuerpo.
422	`pix_nao_creditado`	El `endToEndId` no es de un Pix acreditado en esta cuenta, o el Pix está retenido (`ex.situacaoFundos` `RETIDO`).
422	`devolucao_unica`	En esta cuenta cada Pix acepta una única devolución, y este ya tiene una.
422	`devolucao_so_integral`	En esta cuenta la devolución es solo del valor completo del Pix, y el `valor` solicitado es menor.
422	`devolucao_de_outra_conta`	El Pix entró antes de que el saldo de su cuenta fuera transferido de institución. Su devolución la hacemos nosotros: hable con soporte.
422	`devolucao_excede_recebido`	La suma de las devoluciones superaría el valor recibido.
422	`devolucao_prazo_excedido`	Pasaron 90 días desde la liquidación.
422	`saldo_insuficiente`	El disponible no cubre el valor.
503	`capacidade_indisponivel`	La cuenta no tiene `capacidades.devolucao`.