> 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-pix/cancelando-um-qrcode.md).

# Cancelando um QRCode

## Cancelando um QRCode

O cancelamento de um QRCode na API do Pagou permite invalidar um QRCode Pix ativo (com ou sem vencimento), tornando-o não mais utilizável para pagamento. .

### Visão Geral Técnica

O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/pix/{id}` solicita o cancelamento de um QRCode identificado por seu ID único no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). A operação é síncrona, retornando `204 No Content` para indicar que o cancelamento foi bem-sucedido, e o status do QRCode é alterado para <mark style="color:orange;">`StatusCanceled`</mark>. Este endpoint é útil para invalidar QRCodes antes de sua expiração ou em caso de erro na criação.

**Especificações**:

* **Método**: <mark style="color:red;">`DELETE`</mark>
* **URL**:
  * Produção: `https://api.pagou.com.br/v1/pix/{id}`
  * Sandbox: `https://sandbox-api.pagou.com.br/v1/pix/{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.

### Cabeçalhos

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

### Parâmetros da URL

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

**Validações**:

* O QRCode deve estar no status <mark style="color:orange;">`StatusActive`</mark> para ser cancelado. QRCodes em <mark style="color:orange;">`StatusEmpty`</mark>, <mark style="color:orange;">`StatusCanceled`</mark>, <mark style="color:orange;">`StatusCompleted`</mark> ou <mark style="color:orange;">`StatusRefunded`</mark> não podem ser cancelados.

**Notas Técnicas**:

* O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/pix/{id}` transita o status do QRCode de <mark style="color:orange;">`StatusActive`</mark> para StatusCanceled.
* QRCodes em estados diferentes de <mark style="color:orange;">`StatusActive`</mark> (ex.: <mark style="color:orange;">`StatusCompleted`</mark>, <mark style="color:orange;">`StatusCanceled`</mark>) resultarão em erro 400 Bad Request.

### Resposta

* **Status**: 204 No Content
* **Corpo**: Nenhum (a resposta não contém corpo, indicando sucesso no cancelamento).

### Exemplos de Código

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

```ruby
curl -X DELETE https://sandbox-api.pagou.com.br/v1/pix/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 qrcodeId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://sandbox-api.pagou.com.br/v1/pix/${qrcodeId}`;
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(`QRCode ${qrcodeId} cancelado com sucesso`);
    })
    .catch(error => console.error('Erro na requisição:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import re

# Configuração
qrcode_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://sandbox-api.pagou.com.br/v1/pix/{qrcode_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"QRCode {qrcode_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 QRCode não está no status StatusActive. | Verificar formato do id e consultar status com <mark style="color:purple;">`GET`</mark>` ``/v1/pix/{id}`. |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                                   | Verificar chave.                                                                                          |
| 500         | Internal Server Error | Erro interno da API.                                               | Tentar novamente e contatar <contato@pagou.com.br>.                                                       |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "QRCode is not in active status"
}
```

### Boas Práticas Técnicas

* **Verificação Prévia**: Consulte o status do QRCode com GET /v1/pix/{id} (veja Consultando um QRCode) para confirmar que está em StatusActive antes de tentar cancelar.
* **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições.
* **Monitoramento**: Registre todas as requisições e respostas (incluindo id e código de status HTTP) em logs para auditoria e depuração.
* **Confirmação de Cancelamento**: Após o cancelamento, use <mark style="color:purple;">`GET`</mark>` ``/v1/pix/{id}` para verificar se o status mudou para StatusCanceled.
* **Testes no Sandbox**: Use `https://sandbox-api.pagou.com.br/v1/pix/{id}` para simular cancelamentos sem impacto em produção.
* **Gestão de Erros**: Trate erros 400 para evitar tentativas de cancelamento de QRCodes já pagos (<mark style="color:orange;">`StatusCompleted`</mark>) ou cancelados (<mark style="color:orange;">`StatusCanceled`</mark>).