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 padrao EMVCo adaptado pelo Banco Central

O BR Code do Pix e o formato de payload por tras de todo Pix copia-e-cola e de todo QR Code Pix gerado no Brasil. Nao se trata de um formato proprietario inventado pelo Banco Central do Brasil (BACEN). Na pratica, o BACEN adotou a especificacao internacional EMVCo Merchant-Presented Mode (MPM) QR Code Specification e a perfilou com regras especificas do Pix no Manual de Padroes para Iniciacao do Pix. A simbologia do QR Code em si segue a norma ISO/IEC 18004, enquanto a codificacao do payload segue o EMVCo MPM v1.1.

Na pratica, isso significa que um payload Pix e uma string ASCII pura de digitos e letras maiusculas, estruturalmente identica aos QR Codes de pagamento da India, Singapura e outros paises que adotaram o EMVCo MPM. A diferenca 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 codificacao TLV (Tag-Length-Value). Cada campo comeca com uma tag numerica de 2 digitos, seguida por um length decimal de 2 digitos (numero de caracteres do valor, nao de bytes), e em seguida o value literal. O leitor percorre a string da esquerda para a direita, le 4 caracteres de cabecalho, pula length caracteres e inicia o proximo campo. Algumas tags (notavelmente 26-29 e 62) sao templates cujo valor e por sua vez uma sequencia de sub-campos TLV.

Exemplo de payload Pix estatico minimo (quebras de linha adicionadas para leitura, o payload real e uma string unica):

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) - obrigatorio, sempre 01 para EMVCo v1.
• 01 Point of Initiation Method - 11 para QR estatico (reutilizavel) e 12 para QR dinamico (uso unico). 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 = informacao adicional ou 25 = URL para QR dinamico.
• 52 Merchant Category Code (MCC) - ISO 18245; tipicamente 0000 para Pix pessoa-a-pessoa.
• 53 Transaction Currency - codigo numerico 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 - ate 25 caracteres ASCII, sem acentos.
• 60 Merchant City - ate 15 caracteres ASCII.
• 62 Additional Data Field Template - o sub-campo 05 e o TxID (referencia da transacao), essencial para conciliacao.
• 63 CRC16 - 4 caracteres hexadecimais maiusculos, ultimo campo obrigatorio.

Pix estatico vs dinamico (cobranca imediata e com vencimento)

Um BR Code Pix estatico e gerado uma vez e pode ser reutilizado por varios pagadores - e o classico adesivo do recebedor exposto no caixa. O valor pode ser fixo ou aberto; o TxID costuma ser uma string fixa como ***, significando "sem referencia especifica". O payload e auto-contido: o banco do pagador le a chave e o valor diretamente da string e inicia a transferencia Pix.

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

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

O ultimo campo de todo BR Code e a sequencia 6304XXXX, onde XXXX e o checksum CRC-16/CCITT-FALSE calculado sobre toda a string do payload, incluindo o literal 6304. Parametros: polinomio 0x1021, valor inicial 0xFFFF, sem reflexao de entrada ou saida, sem XOR final. O resultado e formatado como 4 caracteres hexadecimais maiusculos.

O CRC existe para detectar erros de transcricao (um digito perdido durante o copia-cola, um erro de OCR, um QR escaneado corrompido). Nao e uma assinatura criptografica - qualquer um pode recalcula-lo - mas todo aplicativo de banco compativel com Pix recusa um payload cujo CRC nao confira. Validar o CRC no servidor antes de armazenar ou repassar um BR Code e uma sanidade basica 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.
• Geracao de cobrancas - construir payloads programaticamente para faturas e validar o ida-e-volta decodificando a propria saida.
• Conciliacao - extrair o TxID da tag 62.05 e vincular ao ID de pedido interno.
• Antifraude - decodificar payloads colados pelo usuario 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 restricoes BACEN (limites de tamanho, charset, MCC).

FAQ

O BR Code e criptografado? Nao. E TLV em ASCII puro. Tudo escrito num payload estatico fica visivel 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 tambem que esta usando CRC-16/CCITT-FALSE, e nao a variante CCITT pura nem a XMODEM.

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

Qual o tamanho maximo do payload? O proprio QR Code limita pela capacidade da ISO/IEC 18004. Na pratica, BR Codes Pix ficam abaixo de ~300 caracteres em estatico e ~500 em dinamico, confortavelmente dentro das versoes 10-15 do QR no nivel de correcao M.

Fontes: BACEN Manual de Padroes 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).