Criar devolução
POST/v1/charges/:id/refundsDevolve uma cobrança paga a quem pagou, toda ou em parte. O valor sai do seu disponível na hora do pedido e volta ao pagador pelo mesmo provedor que recebeu; se a devolução falhar, ele volta ao seu disponível. Escopo da chave: charges em write.
Cabeçalhos
AuthorizationtextoobrigatórioBearer com a sua chave: sk_test_… no teste, sk_live_… em produção.Idempotency-KeytextoobrigatórioUm valor único por pedido (ex.: o número do pedido), até 255 caracteres visíveis, sem espaços. Mesmo corpo de novo: a resposta guardada, com Idempotent-Replayed: true. Outro corpo: 409. Vale por 7 dias.Content-Typetextoobrigatórioapplication/json
A cobrança entra na comparação da Idempotency-Key: a mesma chave numa cobrança diferente é outro pedido e responde 409.
Corpo
amounttextoopcionalQuanto devolver, em texto decimal com ponto, ex.: "50.00". Sem o campo, devolve tudo o que ainda pode ser devolvido.reasontextoopcionalMotivo curto, até 300 caracteres. Pode ir ao provedor: não ponha dado pessoal.
A devolução sempre vai para quem pagou, pelo mesmo caminho. Mandar dinheiro para outra chave PIX é um pagamento, não uma devolução.
Quando dá para devolver
- Só cobrança
PAIDouPARTIALLY_REFUNDED. Em disputa (MED), espere a decisão. - Até o que ainda pode ser devolvido: o pago menos as devoluções que não falharam (as em andamento contam) e menos o que já voltou num MED perdido.
- Dentro do prazo de devolução, contado da data do pagamento. Passou: REFUND_WINDOW_EXPIRED, com o número de dias na mensagem.
- O provedor que recebeu precisa fazer devoluções pela plataforma; há provedor que aceita uma só devolução por cobrança.
- O seu disponível precisa cobrir o valor.
Status e efeitos
| Status | O que significa |
|---|---|
REQUESTED | Na fila para ir ao provedor. |
PROCESSING | Aceita pelo provedor, esperando o resultado. |
UNKNOWN | O envio não teve resposta clara: a plataforma consulta o provedor antes de qualquer nova tentativa. Para você, é "processando". |
SUCCEEDED | O dinheiro voltou ao pagador. endToEndId e refundedAt preenchidos. |
FAILED | Não foi concluída; o valor voltou ao seu disponível. statusReason diz o motivo. |
A cobrança só muda quando a devolução é concluída: vira PARTIALLY_REFUNDED ou, quando tudo voltou, REFUNDED, e amountRefunded soma o valor. O recurso refund traz também fee e total (o que saiu do disponível).
refund.createdrefund.succeededrefund.failedcharge.partially_refundedcharge.refunded
Erros
| Código | HTTP | Quando acontece |
|---|---|---|
CHARGE_NOT_REFUNDABLE | 409 | A cobrança não está paga ou já foi devolvida por inteiro. |
CHARGE_DISPUTED | 409 | A cobrança está em disputa (MED): a devolução fica disponível depois da decisão. |
REFUND_EXCEEDS_REFUNDABLE | 422 | O valor passa do que ainda pode ser devolvido; o máximo vem em error.details.refundable. |
REFUND_WINDOW_EXPIRED | 422 | Passou o prazo de devolução desta cobrança. |
REFUND_UNAVAILABLE | 422 | O provedor que recebeu não devolve pela plataforma, ou aceita uma devolução por cobrança e esta já tem uma. |
INSUFFICIENT_BALANCE | 422 | O disponível não cobre a devolução. Nada foi criado. |
VALIDATION_ERROR | 422 | Valor fora do formato, zero ou com casas demais. |
NOT_FOUND | 404 | A cobrança não existe nesta empresa e neste ambiente. |
REFUNDS_DISABLED | 503 | Devoluções pausadas pela plataforma. Tente mais tarde com a mesma Idempotency-Key. |
Consultar devoluções
| Rota | Escopo | O que devolve |
|---|---|---|
GET /v1/charges/:id/refunds | charges: read | As devoluções da cobrança, da mais antiga para a mais nova, em data.items (sem cursor). |
GET /v1/refunds/:id | charges: read | Uma devolução (re_…). |
No ambiente de teste, um reason com "falha" no texto faz a devolução falhar. Veja Ambiente de teste.