Cobranças

Cancelar cobrança

DELETE/v1/charges/:chargeId

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

charges/write

Path Parameters

chargeIdstringobrigatório

Identificador devolvido na criação da cobrança

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}.

← Anterior

Status da cobrança

PDF do boleto

const url = 'https://sandbox.validapay.com.br/v1/charges/:chargeId';

const options = {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200 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
  }
}

200200 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
  }
}

400400 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"
  }
}

404404▾

JSON

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

← Anterior

Status da cobrança

PDF do boleto