Decodificador Pix

Como o BR Code funciona?

O Pix se apoia no padrão EMV-QR Code, montado com campos TLV. Cada campo tem ID de 2 dígitos, tamanho de 2 dígitos e o valor.

Entre os campos mais comuns estão: 00 (versão), 26 (chave Pix dentro de subtags), 52 (categoria), 53 (moeda, em que 986 = BRL), 54 (valor opcional), 58 (BR), 59 (nome), 60 (cidade), 62 (txid) e 63 (CRC16 dos bytes anteriores).

Conferir o CRC garante a integridade do código.

BR Code do Pix: o padrão EMVCo adaptado pelo Banco Central

O BR Code do Pix e o formato de payload por trás de todo Pix copia-e-cola e de todo QR Code Pix gerado no Brasil. Não se trata de um formato proprietário inventado pelo Banco Central do Brasil (BACEN). Na pratica, o BACEN adotou a especificação internacional EMVCo Merchant-Presented Mode (MPM) QR Code Specification e a perfilou com regras específicas do Pix no Manual de Padrões para Iniciacao do Pix. A simbologia do QR Code em si segue a norma ISO/IEC 18004, enquanto a codificação do payload segue o EMVCo MPM v1.1.

Na pratica, isso significa que um payload Pix e uma string ASCII pura de dígitos e letras maiúsculas, estruturalmente identica aos QR Codes de pagamento da Índia, Singapura e outros paises que adotaram o EMVCo MPM. A diferença esta no container de conta do recebedor, que identifica o esquema de pagamento como BR.GOV.BCB.PIX e carrega a chave Pix (CPF, CNPJ, e-mail, telefone ou chave aleatoria EVP). Para um dev, decodificar um BR Code e um exercicio deterministico de parsing, sem estado oculto: cada byte da string mapeia para um campo rotulado.

Estrutura TLV: como decodificar um payload byte a byte

O EMVCo MPM usa codificação TLV (Tag-Length-Value). Cada campo começa com uma tag numérica de 2 dígitos, seguida por um length decimal de 2 dígitos (número de caracteres do valor, não de bytes), e em seguida o value literal. O leitor percorre a string da esquerda para a direita, le 4 caracteres de cabeçalho, pula length caracteres e inicia o próximo campo. Algumas tags (notavelmente 26-29 e 62) são templates cujo valor e por sua vez uma sequência de sub-campos TLV.

Exemplo de payload Pix estático mínimo (quebras de linha adicionadas para leitura, o payload real e uma string única):

00 02 01
26 36 00 14 BR.GOV.BCB.PIX 01 14 12345678901234567890
52 04 0000
53 03 986
58 02 BR
59 13 FULANO DE TAL
60 08 SAO PAULO
62 07 05 03 ***
63 04 A1B2

Lendo o payload: tag 00 length 02 value 01 significa "Payload Format Indicator = 01". Tag 26 length 36 indica que se segue um template de conta com 36 caracteres, que e parseado recursivamente. A tag 63 sempre encerra o payload com o checksum CRC16 de 4 caracteres.

Principais campos: PFI, Merchant Account (26-29), Amount (54), CRC16 (63)

• 00 Payload Format Indicator (PFI) - obrigatório, sempre 01 para EMVCo v1.
• 01 Point of Initiation Method - 11 para QR estático (reutilizavel) e 12 para QR dinâmico (uso único). Opcional em payloads estaticos.
• 26-29 Merchant Account Information - template. Para o Pix, o BACEN usa a tag 26 com sub-campo 00 = BR.GOV.BCB.PIX (Globally Unique Identifier), 01 = chave Pix e, opcionalmente, 02 = informação adicional ou 25 = URL para QR dinâmico.
• 52 Merchant Category Code (MCC) - ISO 18245; tipicamente 0000 para Pix pessoa-a-pessoa.
• 53 Transaction Currency - código numérico ISO 4217, sempre 986 (BRL).
• 54 Transaction Amount - decimal com ponto, ex.: 100.50. Omitir produz um QR de valor aberto.
• 58 Country Code - ISO 3166-1 alfa-2, sempre BR.
• 59 Merchant Name - até 25 caracteres ASCII, sem acentos.
• 60 Merchant City - até 15 caracteres ASCII.
• 62 Additional Data Field Template - o sub-campo 05 e o TxID (referência da transação), essencial para conciliacao.
• 63 CRC16 - 4 caracteres hexadecimais maiusculos, último campo obrigatório.

Pix estático vs dinâmico (cobranca imediata e com vencimento)

Um BR Code Pix estático e gerado uma vez e pode ser reutilizado por vários pagadores - e o clássico adesivo do recebedor exposto no caixa. O valor pode ser fixo ou aberto; o TxID costuma ser uma string fixa como ***, significando "sem referência especifica". O payload e auto-contido: o banco do pagador le a chave e o valor diretamente da string e inicia a transferência Pix.

Ja os BR Codes dinamicos são de uso único e trazem o sub-campo 25 dentro da tag 26 com uma URL apontando para um payload JWS hospedado pelo PSP (Provedor de Serviços de Pagamento) do recebedor. O app do pagador busca essa URL, valida a assinatura JWS e so então exibe valor e TxID. O BACEN define dois sabores: Pix Cobranca Imediata e Pix Cobranca com Vencimento, sendo este último capaz de carregar juros, multa e desconto codificados no servidor.

CRC16/CCITT-FALSE: por que existe e como validar

O último campo de todo BR Code e a sequência 6304XXXX, onde XXXX e o checksum CRC-16/CCITT-FALSE calculado sobre toda a string do payload, incluindo o literal 6304. Parâmetros: polinomio 0x1021, valor inicial 0xFFFF, sem reflexao de entrada ou saída, sem XOR final. O resultado e formatado como 4 caracteres hexadecimais maiusculos.

O CRC existe para detectar erros de transcricao (um dígito perdido durante o copia-cola, um erro de OCR, um QR escaneado corrompido). Não e uma assinatura criptografica - qualquer um pode recalcula-lo - mas todo aplicativo de banco compatível com Pix recusa um payload cujo CRC não confira. Validar o CRC no servidor antes de armazenar ou repassar um BR Code e uma sanidade básica que captura a maior parte dos payloads malformados.

Casos de uso para devs

• Integracao com ERP - ler BR Codes retornados pela API do PSP e checar se chave, valor e TxID batem com o que o sistema pediu.
• Geração de cobrancas - construir payloads programaticamente para faturas e validar o ida-e-volta decodificando a própria saída.
• Conciliacao - extrair o TxID da tag 62.05 e vincular ao ID de pedido interno.
• Antifraude - decodificar payloads colados pelo usuário antes de seguir o fluxo de pagamento; alertar se o valor exibido divergir do 54 real.
• Debug e QA - confirmar que um gerador de QR de terceiros respeita as regras EMVCo MPM e as restrições BACEN (limites de tamanho, charset, MCC).

FAQ

O BR Code e criptografado? Não. E TLV em ASCII puro. Tudo escrito num payload estático fica visível para qualquer um que escanear.

Por que meu CRC sempre da errado? O CRC precisa ser calculado incluindo o literal 6304. Esquecer esses 4 bytes e o bug mais comum. Confirme também que esta usando CRC-16/CCITT-FALSE, e não a variante CCITT pura nem a XMODEM.

O nome do recebedor pode ter acentos? Não. A tag 59 e restrita a ASCII; remova diacriticos antes de codificar.

Qual o tamanho máximo do payload? O próprio QR Code limita pela capacidade da ISO/IEC 18004. Na pratica, BR Codes Pix ficam abaixo de ~300 caracteres em estático e ~500 em dinâmico, confortavelmente dentro das versões 10-15 do QR no nível de correção M.

Fontes: BACEN Manual de Padrões para Iniciacao do Pix (v2.9.0), Manual do BR Code v2.0.0, EMVCo Merchant-Presented Mode QR Code Specification v1.1, ISO/IEC 18004 (simbologia QR Code), ISO 4217 (moedas), ISO 3166-1 (paises), ISO 18245 (MCC).