# Cancelar cobrança
`DELETE /v1/charges/:chargeId`
**Área:** Cobranças

**Scopes necessários:** `charges/write`

Cancela uma cobrança em aberto. O cancelamento é definitivo: não existe rota para reabrir a cobrança, o caminho é criar uma nova.

**Só cancela cobrança em aberto.** `status` precisa ser `PENDING` ou `AWAITING_PAYMENT`. Qualquer outro valor — incluindo `PAID`, `EXPIRED` e uma cobrança já cancelada — responde `400` com `CHARGE_NOT_CANCELABLE`. Para desfazer um pagamento já liquidado use a devolução Pix ou o estorno de cartão, não esta rota.

Cobrança de outra conta responde `404` com `CHARGE_NOT_FOUND`, igual a um ID inexistente.

**O que o cancelamento arrasta junto**

- A cobrança passa a `CANCELED` e, quando é PIX ou boleto, também é cancelada no provedor — o QR Code e a linha digitável deixam de aceitar pagamento.
- Havendo `invoiceId`, a fatura vai junto para `CANCELED`; o campo volta na resposta.
- Notas fiscais da cobrança são tratadas e o resultado vem em `notas`: `canceled` são as canceladas na prefeitura, `flagged` as marcadas para cancelamento manual, `failed` as que a prefeitura recusou cancelar e `untouched` as que não exigiam ação. Falha ao tratar notas não impede o cancelamento da cobrança — os quatro contadores voltam zerados.
- Sendo a última cobrança em aberto do ciclo de uma assinatura, o ciclo também é cancelado e `cycleNumber` traz o número dele. Fora desse caso, `cycleNumber` é `null`.

Cancelar uma cobrança não cancela a assinatura: o próximo ciclo continua gerando cobrança. Para encerrar a recorrência use `DELETE /v1/subscriptions/{subscriptionId}`.

### Path parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `chargeId` | **sim** | Identificador devolvido na criação da cobrança |

### Resposta 200: 200 Cobrança avulsa

```json
{
  "message": "Cobrança cancelada com sucesso",
  "chargeId": "cha_1771453171013_fp6iocaxb",
  "invoiceId": null,
  "cycleNumber": null,
  "notas": {
    "canceled": 0,
    "flagged": 0,
    "failed": 0,
    "untouched": 0
  }
}
```

### Resposta 200: 200 Cobrança de assinatura

```json
{
  "message": "Cobrança cancelada com sucesso",
  "chargeId": "cha_1788279663277_8qjtrcyri",
  "invoiceId": "inv_1788279648820_3yicz75vb",
  "cycleNumber": 3,
  "notas": {
    "canceled": 1,
    "flagged": 0,
    "failed": 0,
    "untouched": 0
  }
}
```

### Resposta 400: 400 Cobrança não cancelável

```json
{
  "error": {
    "message": "Apenas cobranças pendentes ou aguardando pagamento podem ser canceladas",
    "code": "CHARGE_NOT_CANCELABLE",
    "details": null,
    "timestamp": "2026-09-14T18:20:00.000Z"
  }
}
```

### Resposta 404: 404

```json
{
  "error": {
    "message": "Cobrança não encontrada",
    "code": "CHARGE_NOT_FOUND",
    "details": null,
    "timestamp": "2026-09-14T18:20:00.000Z"
  }
}
```

---
Página: https://docs.validapay.com.br/referencia/delete-cancelar-cobranca
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json