Consultando um QRCode

A consulta de um QRCode na API do Pagou permite obter os detalhes de um QRCode Pix (com ou sem vencimento), incluindo seu status, valor, pagador e código Pix.

Visão Geral Técnica

O endpoint GET /v1/pix/{id} retorna os detalhes de um QRCode identificado por seu ID único no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). A operação é síncrona, retornando 200 OK com um corpo JSON contendo informações como status, valor, pagador, código Pix e imagem em base64. Este endpoint é útil para verificar o estado de um pagamento Pix (ex.: pago ou expirado) ou recuperar o código Pix para exibição.

Especificações:

• Método: GET

• URL:

  • Produção: https://api.pagou.com.br/v1/pix/{qrcodeID}

  • Sandbox: https://sandbox.api.pagou.com.br/v1/pix/{qrcodeID}

• Autenticação: Cabeçalho X-API-KEY com chave do painel.

• Content-Type: application/json

• Resposta: Status 200 OK com corpo JSON contendo os detalhes do QRCode.

• Erros: 400 Bad Request, 401 Unauthorized, 404 Not Found, 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:

• qrcodeID: Deve ser um UUID válido (ex.: 550e8400-e29b-41d4-a716-446655440000).

Notas Técnicas:

• Configure o notification_url ao criar o QRCode para receber o evento QRCodeCompleted quando o status mudar para StatusCompleted ou QRCodeRefunded quando o status mudar para StatusRefunded.

Resposta

• Status: 200 OK

• Corpo: JSON com os detalhes do QRCode, incluindo status, valor, pagador, código Pix e imagem em base64.

Exemplo de Resposta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "cust-12345",
  "amount": 100.00,
  "description": "Payment with due date",
  "expiration": 30,
  "due_date": "2024-12-31",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": [
    {
      "key": "order_id",
      "value": "ORD-2024-001"
    }
  ],
  "payer": {
    "name": "João Silva",
    "document": "12345678901"
  },
  "discount": {
    "type": "fixed",
    "amount": 10.00,
    "limit_date": "2024-12-25"
  },
  "fine": {
    "type": "percentage",
    "amount": 2.5
  },
  "interest": {
    "type": "percentage_calendar_days",
    "amount": 1.0
  },
  "notification_url": "https://your-webhook.com/notifications",
  "payload": {
    "payload_id": 12345,
    "data": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540100.005802BR5913JOAO SILVA6008SAO PAULO62070503***63041234",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAAdgAAAHYBTnsmCAAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAANCSURBVHic7doxAQAAAMKg9U9tCj+gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4GvAAAEAAQ=="
  }
}

Campos da Resposta:

Campo	Tipo	Descrição
id	string	UUID único do QRCode (ex.: 550e8400-e29b-41d4-a716-446655440000).
customer_id	string	Identificador interno do cliente (ex.: cust-12345).
amount	number	Valor do pagamento em reais (ex.: 100.00).
description	string	Descrição do pagamento (máx. 255 caracteres).
expiration	number	Tempo de expiração do QRCode (em dias para QRCodes com vencimento, ou segundos para QRCodes simples).
due_date	string	Data de vencimento, se aplicável (formato YYYY-MM-DD).
status	string	Status atual do QRCode (empty, active, canceled, completed, refunded).
created_at	string	Data de criação do QRCode (formato ISO 8601).
updated_at	string	Data da última atualização (formato ISO 8601).
metadata	array	Pares chave-valor para dados adicionais.
metadata[].key	string	Chave do metadado (ex.: order_id).
metadata[].value	string	Valor do metadado (ex.: ORD-2024-001).
payer	object	Dados do pagador.
payer.name	string	Nome completo do pagador (máx. 100 caracteres).
payer.document	string	CPF (11 dígitos) ou CNPJ (14 dígitos).
discount	object	Desconto para pagamento antecipado, se aplicável.
discount.type	string	Tipo de desconto (fixed, percentage, fixed_calendar_days).
discount.amount	number	Valor do desconto (em reais ou percentual).
discount.limit_date	string	Data limite para o desconto (formato YYYY-MM-DD).
fine	object	Multa por atraso, se aplicável.
fine.type	string	Tipo de multa (percentage, fixed, etc.).
fine.amount	number	Valor da multa (em percentual ou reais).
interest	object	Juros por atraso, se aplicável.
interest.type	string	Tipo de juros (percentage_calendar_days, fixed, percentage.).
interest.amount	number	Valor dos juros (em percentual ou reais).
notification_url	string	URL HTTPS para webhooks.
payload	object	Dados do QRCode Pix.
payload.payload_id	number	ID interno do payload Pix.
payload.data	string	Código Pix para pagamento (copia-e-cola).
payload.image	string	Imagem do QRCode em base64 (formato data:image/png;base64,...).

Exemplos de Código

cURL

curl -X GET 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"

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: 'GET',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        return response.json();
    })
    .then(data => {
        console.log(`QRCode ID: ${data.id}`);
        console.log(`Status: ${data.status}`);
        console.log(`Valor: ${data.amount}`);
        console.log(`Código Pix: ${data.payload.data}`);
        console.log(`Imagem Base64: ${data.payload.image}`);
    })
    .catch(error => console.error('Erro na requisição:', error));

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.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    print(f"QRCode ID: {data['id']}")
    print(f"Status: {data['status']}")
    print(f"Valor: {data['amount']}")
    print(f"Código Pix: {data['payload']['data']}")
    print(f"Imagem Base64: {data['payload']['image']}")
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.	Verificar formato do id.
401	Unauthorized	X-API-KEY inválido ou ausente.	Verificar chave.
404	Not Found	QRCode com o id não existe.	Verificar o id fornecido.
500	Internal Server Error	Erro interno da API.	Tentar novamente e contatar [email protected].

Exemplo de Resposta de Erro:

{
  "error": "QRCode not found"
}

Boas Práticas Técnicas

• Validação de Dados: Valide o id como UUID antes de enviar a requisição.

• 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, status, payload.data e payload.image) em logs para auditoria e depuração.

• Testes no Sandbox: Use https://sandbox.api.pagou.com.br/v1/pix/{id} para simular consultas sem impacto em produção.

• Uso da Imagem: Converta o campo payload.image (base64) em uma imagem PNG para exibição em interfaces (ex.: <img src="{payload.image}"> em HTML).

• Verificação de Status: Use o campo status para determinar ações subsequentes (ex.: exibir o código Pix se active, ou notificar o usuário se canceled)