退款

将收到的 Pix 全部或部分退还给付款人。id 由您生成。允许部分退款，直到累计金额达到原始金额，期限为结算后 90 天内。

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

权限范围：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" }
}

结果通过 webhook devolucao.concluida 或 devolucao.nao_realizada 送达。退款免费。

能否退款取决于收到该 Pix 的账户：GET /v2/ex/config 返回 capacidades.devolucao（子账户的 Pix 请带 ?subconta=）。为 false 时，该路由返回 503 capacidade_indisponivel，detail 会说明是哪个账户以及原因。

在某些账户中，只能退还 Pix 的全额。在这些账户中，valor 小于收到的金额时返回 422 devolucao_so_integral，且不会预留任何金额。

如果 Pix 到账后您的账户更换了机构，退款会从该 Pix 到账的账户发出。调用方式不变。如果账户余额已从一家机构转移到另一家机构，转移前到账的 Pix 的退款会返回 422 devolucao_de_outra_conta，退款由我们处理。

查询 #

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

权限范围：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 使用游标列出您发起的退款。我们发起的退款不在其中：它们只通过 webhook devolucao.criada（带 motivo）送达，并以 devolucao.concluida 结束。我们发起的退款也可能以 devolucao.nao_realizada 结束：这笔 Pix 没有退回付款人，已入账给您。它的 motivo 与 devolucao.criada 中的相同：是这笔 Pix 被拒绝的原因。同一笔 Pix 的 pix.creditado 会单独送达，可能在它之前或之后：两者之间的顺序不作保证。

错误 #