Devoluções de PIX

POST /v1/cobrancas/{id}/devolver

Escopo cobrancas:devolver. Devolve ao pagador um PIX recebido, no todo ou em parte.

Campo	Tipo
valor	inteiro	Em centavos. Vazio: devolve o que resta do pagamento
endToEndId	texto	O pagamento a devolver. Vazio: o único pagamento da cobrança com valor a devolver
motivo	texto	Até 140 caracteres; vai para o pagador

{ "valor": 500, "motivo": "Produto em falta no pedido" }

A resposta é 202 com a cobrança e a devolução em devolucoes, como solicitada. O banco conclui em seguida:

status
solicitada	Na fila para o banco
em_processamento	O banco aceitou e está concluindo
devolvida	Dinheiro devolvido; idDevolucao é o identificador no Banco Central
nao_realizada	O banco recusou; veja motivoFalha

Regras

• Só PIX pago pelo banco (baixas manuais não entram) e só até 90 dias do pagamento (regra do Banco Central): depois, 409 REFUND_EXPIRED.
• A soma das devoluções nunca passa do valor pago. Pedir mais: 422, com quanto resta.
• Devolvida por inteiro, a cobrança vira devolvida; em parte, continua paga com a lista de devoluções.
• Cada devolução é pedida ao banco uma única vez, mesmo se você repetir a chamada (use a Idempotency-Key) ou se a comunicação cair no meio.

Quando a devolução termina, o seu sistema recebe cobranca.devolvida ou cobranca.devolucao_recusada nos avisos.