Estornar uma cobrança

Devolve ao pagador o valor integral de uma cobrança confirmada. Vale para assinaturas em qualquer status — inclusive canceladas. É contrato estável: pode basear nele o atendimento de CDC.

POST/api/v1/subscriptions/:id/charges/:chargeId/refund

A requisição não leva corpo.

{
  "status": "success",
  "data": {
    "id": 790,
    "subscriptionId": 12,
    "status": 3,
    "value": 2990,
    "amount": 29.9,
    "dueDate": "2026-09-09",
    "acquirerPaymentId": "0279e54a-88df-4b06-874b-65785c45a19f",
    "denialCode": "",
    "denialMessage": "",
    "attempts": 1,
    "nextRetryAt": null,
    "paymentTransactionId": 63,
    "createdAt": "2026-09-09T19:48:57.304828Z",
    "updatedAt": "2026-10-06T14:02:10.5531Z",
    "idempotent": false
  }
}

Situação	HTTP	Mensagem / corpo
Cobrança `CONFIRMED`	`200`	`idempotent: false`. Cobrança vai a `3 REFUNDED` e `charge.refunded` é disparado
Cobrança já `REFUNDED`	`200`	`idempotent: true`. Nenhum novo webhook
Cobrança inexistente ou de outra assinatura	`404`	`Charge not found`
Cobrança `PENDING` ou `DENIED`	`409`	`Charge is not refundable`
Assinatura inexistente	`404`	`Subscription not found`
Assinatura de outro lojista	`403`	`Forbidden`
Falha no adquirente	`502`	`Refund failed`. A cobrança continua `CONFIRMED` — pode repetir

Idempotente, inclusive em paralelo

Repetir a chamada — em sequência ou ao mesmo tempo — nunca estorna duas vezes nem gera dois charge.refunded: só uma chamada aplica o estorno, as demais voltam idempotent: true. Em caso de timeout, pode repetir com segurança.

O estorno não cancela a assinatura. Para encerrar o contrato, chame também POST /cancel (Cancelar assinatura). Na assinatura, lastChargeStatus passa a "REFUNDED". Estorno parcial não é suportado. O prazo para o valor aparecer na fatura do pagador segue as regras do emissor do cartão.