> For the complete documentation index, see [llms.txt](https://docs.pagou.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-boleto/cancelando-um-boleto.md).

# Cancelando um Boleto

## Cancelando um Boleto

O cancelamento de um boleto na API do Pagou permite invalidar um boleto ativo, alterando seu status para <mark style="color:red;background-color:red;">`StatusCanceled`</mark> e tornando-o não mais válido para pagamento.

### Visão Geral Técnica

O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/charges/{chargeID}` solicita o cancelamento de um boleto identificado por seu ID único. A operação é síncrona, retornando `204 No Content` em caso de sucesso, indicando que o boleto foi cancelado e seu status atualizado para <mark style="color:red;">`StatusCanceled`</mark>. Apenas boletos no status <mark style="color:red;">`StatusActive`</mark> (ou, em casos raros, <mark style="color:red;">`StatusEmpty`</mark>) podem ser cancelados. Boletos em <mark style="color:red;">`StatusPaid`</mark>, <mark style="color:red;">`StatusRefunded`</mark> ou já em <mark style="color:red;background-color:red;">`StatusCanceled`</mark> não podem ser cancelados novamente.

**Especificações**:

* **Método**: DELETE
* **URL**:
  * Produção: `https://api.pagou.com.br/v1/charges/{id}`
  * Sandbox: `https://sandbox-api.pagou.com.br/v1/charges/{id}`
* **Autenticação**: Cabeçalho X-API-KEY com chave do painel.
* **Content-Type**: `application/json`
* **Resposta**: Status `204 No Content` (sem corpo).
* **Erros**: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error.

### Pré-requisitos

* **Conta no Pagou**: Acesse <https://pagou.com.br> e crie uma conta.
* **Chave de API**: Obtenha a chave em *Configurações > API* (diferentes para sandbox e produção).
* **ID do boleto**: Use o UUID retornado no header Location ao criar o boleto (ex.: 550e8400-e29b-41d4-a716-446655440000).
* **Ferramentas**: Use cURL, Postman ou bibliotecas HTTP (ex.: requests em Python, fetch em JavaScript).

### Endpoint

* **Método**: DELETE
* **URL**: <https://api.pagou.com.br/v1/charges/{id}> (produção) ou <https://sandbox-api.pagou.com.br/v1/charges/{id}> (sandbox)

### Cabeçalhos

| Cabeçalho    | Valor                  | Descrição                                                    |
| ------------ | ---------------------- | ------------------------------------------------------------ |
| X-API-KEY    | sua\_chave\_api        | Chave de autenticação (encontrada em *Configurações > API*). |
| Content-Type | application/json       | Formato JSON para a requisição.                              |
| User-Agent   | NomeDaSuaAplicacao/1.0 | Identificador da aplicação (ex.: MinhaLoja/1.0, opcional).   |

### Parâmetros da URL

| Parâmetro | Tipo   | Obrigatório | Descrição                                                                       |
| --------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| `id`      | string | Sim         | ID único do boleto no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). |

**Validações**:

* id: Deve ser um UUID válido (ex.: 550e8400-e29b-41d4-a716-446655440000).
* O boleto deve estar em <mark style="color:red;">StatusActive</mark> ou, em casos raros, <mark style="color:red;">`StatusEmpty`</mark>. Boletos em outros status (ex.: <mark style="color:red;">StatusPaid</mark>) resultarão em erro 400.

### Resposta

* **Status**: 204 No Content
* **Corpo**: (Vazio, conforme padrão para 204).

**Exemplo de Resposta**:

```bash
HTTP/1.1 204 No Content
Content-Length: 0
```

### Mapa de Status e Cancelamento

O cancelamento altera o status do boleto para StatusCanceled. Abaixo está o contexto dos status, conforme definido na API do Pagou:

| Status           | Valor Numérico | Descrição                                                                                |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `StatusEmpty`    | 1              | Estado inicial transitório, indicando que o boleto foi criado, mas ainda não está ativo. |
| `StatusActive`   | 2              | Boleto ativo, pronto para pagamento, com código de barras e PDF disponíveis.             |
| `StatusCanceled` | 3              | Boleto cancelado, não mais válido para pagamento.                                        |
| `StatusPaid`     | 4              | Boleto pago pelo cliente, com liquidação confirmada.                                     |
| `StatusRefunded` | 5              | Boleto pago, mas reembolsado ao cliente.                                                 |

**Impacto do Cancelamento**:

* **Condição**: Apenas boletos em StatusActive (ou, raramente, StatusEmpty) podem ser cancelados.
* **Resultado**: O boleto transita para StatusCanceled, tornando-o inválido para pagamento.
* **Verificação**: Após o cancelamento, use <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar o status <mark style="color:red;">StatusCanceled</mark> (veja Consultando um Boleto).
* **Webhooks**: O cancelamento não gera notificações via webhook.

### Exemplos de Código

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X DELETE https://sandbox-api.pagou.com.br/v1/charges/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaLoja/1.0"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fetch = require('node-fetch');

// Configuração
const chargeId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://sandbox-api.pagou.com.br/v1/charges/${chargeId}`;
const headers = {
    'X-API-KEY': 'sua_chave_api',
    'Content-Type': 'application/json',
    'User-Agent': 'MinhaLoja/1.0'
};

fetch(url, {
    method: 'DELETE',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        console.log(`Status: ${response.status} - Boleto ${chargeId} cancelado com sucesso`);
    })
    .catch(error => console.error('Erro na requisição:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import re

# Configuração
charge_id = "550e8400-e29b-41d4-a716-446655440000"
url = "https://sandbox-api.pagou.com.br/v1/charges/{charge_id}"
headers = {
    "X-API-KEY": "sua_chave_api",
    "Content-Type": "application/json",
    "User-Agent": "MinhaLoja/1.0"
}

try:
    response = requests.delete(url, headers=headers)
    response.raise_for_status()
    print(f"Status: {response.status_code} - Boleto {charge_id} cancelado com sucesso")
except requests.RequestException as e:
    print(f"Erro na requisição: {e}")
    if e.response:
        print(f"Detalhes: {e.response.json()}")
```

{% endtab %}
{% endtabs %}

### Tratamento de Erros

| Código HTTP | Descrição             | Possível Causa                                                              | Solução                                                    |
| ----------- | --------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 400         | Bad Request           | id não é um UUID válido ou boleto não está em `StatusActive`/`StatusEmpty`. | Verificar formato do id e status via GET /v1/charges/{id}. |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                                            | Verificar chave.                                           |
| 500         | Internal Server Error | Erro interno da API.                                                        | Tentar novamente e contatar <suporte@pagou.com.br>.        |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "Charge is not in a cancellable state"
}
```

### Boas Práticas Técnicas

* **Validação de Dados**: Valide o id como UUID (formato 8-4-4-4-12) antes de enviar a requisição. Use <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar se o boleto está em <mark style="color:red;">`StatusActive`</mark> antes de cancelar.
* **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições.
* **Verificação Pós-Cancelamento**: Após o cancelamento, consulte o boleto com <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar o status StatusCanceled.
* **Testes no Sandbox**: Use `https://sandbox-api.pagou.com.br/v1/charges/{id}` para simular cancelamentos sem impacto em produção.
* **Monitoramento**: Registre todas as requisições e respostas (incluindo id e status HTTP) em logs para auditoria e depuração.