Guia de Cobrança com QR Code

Este guia cobre o caso de uso de recebimento via QR Code, do momento de criação da cobrança até a confirmação de pagamento.

Quando usar este fluxo

Use cobrança com QR Code quando você precisa:

• Receber pagamento em checkout (site/app/PDV);
• Gerar um QR Code único por pedido;
• Conciliar pagamento com seu pedido interno usando external_id.

Pré-requisitos

1. Token JWT válido (veja Guia de Autenticação);
2. Header Authorization: Bearer <token> em todas as chamadas;
3. Valores monetários em centavos no campo amount.

Fluxo da cobrança

Passo 1 - Criar a cobrança

Endpoint de referência: Criar uma cobrança via QRCode

POST /v1/connect/charge?base64=true HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 15990,
  "external_id": "pedido-2026-000981",
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "payer": {
    "name": "Maria Souza",
    "tax_id": "12345678901"
  }
}

Campos importantes:

• amount: valor em centavos;
• external_id: seu identificador de negócio para conciliação;
• key: chave Pix recebedora da sua conta;
• payer: opcional, útil para reconciliação/antifraude.

Passo 2 - Exibir QR Code e Pix Copia e Cola

Na resposta da criação, você recebe os dados da cobrança. Os mais usados no front-end:

• id: identificador interno da cobrança;
• transaction_identification (TXID): identificador Pix da cobrança;
• emvqrcps: código EMV (Pix Copia e Cola);
• base64image (quando base64=true): imagem do QR Code.

Boas práticas:

• Exiba QR Code e também o código Copia e Cola;
• Mostre um contador de validade no checkout;
• Salve id, external_id e transaction_identification na sua base.

Passo 3 - Confirmar pagamento

Você pode confirmar por webhook (recomendado) e por consulta ativa (fallback).

Consulta por ID:

• Consultar por ID

Consulta por external_id:

• Consultar por ID externo

Consulta por TXID:

• Consultar por TXID

Status esperados da cobrança:

• PENDING: aguardando pagamento;
• APPROVED: pago;
• EXPIRED: expirado.

Fluxo recomendado de implementação

1. Criar cobrança ao iniciar checkout;
2. Persistir id, external_id e txid;
3. Exibir QRCode/EMV para o pagador;
4. Receber webhook de confirmação;
5. Atualizar pedido para pago;
6. Se webhook atrasar, consultar por external_id ou txid.

Erros comuns

• 400 BAD_REQUEST: payload inválido (ex.: campo obrigatório ausente);
• 401 UNAUTHORIZED: token ausente/expirado;
• 422 UNPROCESSABLE_ENTITY: regra de validação não atendida.

Sempre registre o meta.request_id para suporte.