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 DELETE /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 StatusCanceled. Este endpoint é útil para invalidar QRCodes antes de sua expiração ou em caso de erro na criação.

Especificações:

Método: DELETE
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 StatusActive para ser cancelado. QRCodes em StatusEmpty, StatusCanceled, StatusCompleted ou StatusRefunded não podem ser cancelados.

Notas Técnicas:

O endpoint DELETE /v1/pix/{id} transita o status do QRCode de StatusActive para StatusCanceled.
QRCodes em estados diferentes de StatusActive (ex.: StatusCompleted, StatusCanceled) 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

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"

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));

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()}")

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 GET /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 [email protected].

Exemplo de Resposta de Erro:

{
  "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 GET /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 (StatusCompleted) ou cancelados (StatusCanceled).

PreviousConsultando um QRCode NextEstornando um QRCode

Last updated 4 months ago