Guia de Pagamento com QR Code (Pix Copia e Cola)

Este guia detalha o fluxo de pagamento por QR Code/Pix Copia e Cola, desde a validação do EMV ate a confirmação da transferência.

Quando usar este fluxo

Use este método quando você recebe do pagador:

Um código Pix Copia e Cola (EMV);
Um QR Code de cobrança de terceiro convertido para EMV no seu sistema.

Pré-requisitos

Token JWT válido (veja Guia de Autenticação);
amount em centavos;
Código emv completo e sem alterações;
external_id único por pagamento para conciliação.

Fluxo do pagamento

Passo 1 - Validar dados do EMV (recomendado)

Antes de pagar, valide o conteúdo do EMV para reduzir risco de erro operacional.

Endpoint de referência: Consultar dados de QRCode

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

{
  "emv": "00020101021226880014br.gov.bcb.pix0136...6304ABCD"
}

Campos úteis na resposta:

key
transaction_identification
amount (quando disponível no EMV)

Passo 2 - Iniciar pagamento com QR Code/EMV

Endpoint de referência: Pagar um QRCode e/ou Pix Copia e Cola

POST /v1/connect/transfer/qrcode HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 20000,
  "emv": "00020101021226880014br.gov.bcb.pix0136...6304ABCD",
  "external_id": "pag-qr-2026-03-001"
}

Campos obrigatórios:

amount
emv

Campo recomendado:

external_id

Passo 3 - Conciliar e acompanhar status

Após iniciar a transferência, persista:

id
external_id
end_to_end_id
transaction_identification
status

Endpoints de consulta:

Status possíveis:

PROCESSING
CONFIRMED
ERROR

Erros comuns

400 BAD_REQUEST: EMV inválido ou payload incorreto;
401 UNAUTHORIZED: token expirado ou ausente;
422 UNPROCESSABLE_ENTITY: regra de validação não atendida.

Sempre armazene meta.request_id para suporte e auditoria.