Criar devolução

POST/v1/charges/:id/refunds

Devolve 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 PAID ou PARTIALLY_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 da devolução
StatusO que significa
REQUESTEDNa fila para ir ao provedor.
PROCESSINGAceita pelo provedor, esperando o resultado.
UNKNOWNO envio não teve resposta clara: a plataforma consulta o provedor antes de qualquer nova tentativa. Para você, é "processando".
SUCCEEDEDO dinheiro voltou ao pagador. endToEndId e refundedAt preenchidos.
FAILEDNã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.created
  • refund.succeeded
  • refund.failed
  • charge.partially_refunded
  • charge.refunded

Erros

Códigos de erro
CódigoHTTPQuando acontece
CHARGE_NOT_REFUNDABLE409A cobrança não está paga ou já foi devolvida por inteiro.
CHARGE_DISPUTED409A cobrança está em disputa (MED): a devolução fica disponível depois da decisão.
REFUND_EXCEEDS_REFUNDABLE422O valor passa do que ainda pode ser devolvido; o máximo vem em error.details.refundable.
REFUND_WINDOW_EXPIRED422Passou o prazo de devolução desta cobrança.
REFUND_UNAVAILABLE422O provedor que recebeu não devolve pela plataforma, ou aceita uma devolução por cobrança e esta já tem uma.
INSUFFICIENT_BALANCE422O disponível não cobre a devolução. Nada foi criado.
VALIDATION_ERROR422Valor fora do formato, zero ou com casas demais.
NOT_FOUND404A cobrança não existe nesta empresa e neste ambiente.
REFUNDS_DISABLED503Devoluções pausadas pela plataforma. Tente mais tarde com a mesma Idempotency-Key.

Consultar devoluções

Rotas de devolução
RotaEscopoO que devolve
GET /v1/charges/:id/refundscharges: readAs devoluções da cobrança, da mais antiga para a mais nova, em data.items (sem cursor).
GET /v1/refunds/:idcharges: readUma devolução (re_…).

No ambiente de teste, um reason com "falha" no texto faz a devolução falhar. Veja Ambiente de teste.