Cancelar uma cobrança
Cancela uma cobrança que ainda não foi paga. Cobrança já paga não se cancela por aqui: isso é estorno, e tem caminho próprio.
Autenticação
Chave de API no cabeçalho Authorization: Bearer naut_live_….
O escopo exigido é charges:write. Uma credencial sem esse escopo recusa com 401, o mesmo código de uma credencial inválida: a recusa não diz se ela existe.
Exige chave de API no cabeçalho. A família da chave decide contra qual ambiente ela escreve, e a chave não fabrica sessão: ela não alcança nenhuma rota fora de /v1.
Parâmetros
Caminho
| Nome | Tipo | Descrição |
|---|---|---|
referenceobrigatório | texto (uuid) | A referência da cobrança a cancelar. |
Respostas
200 · sucesso
{
"amountCents": 129900,
"chargeId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"createdAt": "2026-01-15T12:00:00.000Z",
"currency": "BRL",
"method": "pix",
"payable": {
"emv": "exemplo",
"kind": "pix",
"qrImageUrl": "https://loja.exemplo.com.br/webhooks"
},
"refundedAmountCents": 129900,
"status": "pending"
}401 · não autenticado
A chave de API não foi apresentada, ou não vale.
404 · não encontrado
A referência não existe, ou não é desta conta.
409 · conflito
A cobrança não está num estado que permita cancelamento.
429 · excesso de chamadas
Excesso de chamadas para esta chave.
503 · indisponível
A sua chave é de sandbox e o ambiente de teste desta instalação não está provisionado. Chaves de produção seguem funcionando; repetir a chamada não resolve, e nada foi cancelado.
Erros desta rota
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 401 | UNAUTHORIZED | A chave de API não veio no cabeçalho, veio malformada, foi revogada, ou não pertence a esta instalação. | Confira o cabeçalho e o prefixo da chave. Repetir com a mesma chave devolve sempre 401, e nenhuma chamada desta superfície funciona sem uma chave válida. |
| 404 | V1_CHARGE_NOT_FOUND | A referência não existe nesta instalação, ou existe e pertence a outra conta. As duas causas respondem igual de propósito: distinguir revelaria a existência de cobrança alheia. | Confira a referência que a criação da cobrança devolveu. Repetir não muda o resultado. |
| 409 | V1_CHARGE_NOT_CANCELLABLE | A cobrança existe e o estado dela não admite cancelamento: já foi paga, já foi cancelada, ou já expirou. | Consulte a cobrança para ler o estado. Se ela já foi paga, o caminho é o estorno e não o cancelamento; repetir o cancelamento devolve sempre 409. |
| 429 | API_KEY_RATE_LIMITED | Esta chave passou do teto de chamadas da janela corrente. É limite de FREQUÊNCIA, não de valor. | Espere a janela virar e reenvie, espaçando as chamadas. Nada foi cancelado. |
| 503 | SANDBOX_UNAVAILABLE | A sua chave é da família de teste e esta instalação não tem o ambiente de teste provisionado. Chaves de produção seguem funcionando normalmente. | Use uma chave de produção, ou peça o provisionamento do ambiente de teste. Repetir com a chave de teste não resolve, e nada foi cancelado. |
Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.