Devoluções
Você pode devolver ao pagador, total ou parcialmente, o valor de uma cobrança paga. Também é possível fazer várias devoluções parciais, desde que a soma não passe do valor original.
Solicitar uma devolução
POST /api/charges/{pix_txid}/chargeback
curl -X POST https://marx.loco.ltd/api/charges/0f6e2a3c7c1d4f439b2f5e8d9a4b1c22/chargeback \
-H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"chargeback": {"cancelid": "DEV1001A", "amount": "50.00"}}'
| Campo | Regra |
|---|---|
cancelid |
Seu identificador da devolução: 1 a 35 letras e números, único por cobrança. Repetir o mesmo cancelid devolve a devolução já existente (seguro para novas tentativas). |
amount |
Valor a devolver, maior que zero. A soma das devoluções ativas não pode passar do valor pago. |
A resposta 200 traz a cobrança atualizada, com a devolução em refunds:
{
"pix_txid": "0f6e2a3c7c1d4f439b2f5e8d9a4b1c22",
"pix_status": "DEVOLVIDO",
"lifecycle_status": "reversed",
"refunds": [
{ "refund_id": "DEV1001A", "amount": "50.0", "status": "EM_PROCESSAMENTO", "lifecycle_status": "pending",
"end_to_end_id": null, "confirmed_at": null, "created_at": "2026-10-06T15:10:02-03:00" }
]
}
Ciclo da devolução
status |
lifecycle_status |
Significado |
|---|---|---|
EM_PROCESSAMENTO |
pending |
Pedido aceito, aguardando a liquidação. |
DEVOLVIDO |
reversed |
Dinheiro devolvido ao pagador. |
NAO_REALIZADO |
failed |
A devolução não aconteceu (ex.: conta do pagador encerrada). Veja error_message. |
Quando a devolução termina (DEVOLVIDO ou NAO_REALIZADO) você recebe um webhook da cobrança com um objeto refund descrevendo o resultado.
Nota
O pix_status da cobrança passa para DEVOLVIDO assim que uma devolução é aceita, mesmo parcial. Se todas as devoluções falharem, ela volta para CONCLUIDA. Para saber quanto foi devolvido, some os refunds com lifecycle_status: "reversed".
Quando a devolução é recusada (422)
- a cobrança ainda não foi paga;
- o valor pedido passa do saldo disponível para devolução;
cancelidouamountausentes ou inválidos;- a cobrança é antiga demais para devolução pela regra do Pix (até 90 dias após o pagamento).
Pix Automático
Cobranças de Pix Automático pagas são devolvidas por POST /api/pix_automatico/charges/{id}/refund. Veja Pix Automático.