Como funciona o QR Code Pix.

O formato dos campos

O código é uma string formada por campos colados um no outro. Cada campo tem três partes: dois dígitos de identificador, dois dígitos de tamanho e o conteúdo. O campo 00, com conteúdo 01, vira a sequência 000201.

O tamanho tem sempre dois dígitos, com zero à esquerda. Um conteúdo de nove caracteres tem tamanho 09, não 9. Dois campos são compostos, o 26 e o 62: o conteúdo deles é, por sua vez, uma sequência de campos no mesmo formato.

O tamanho declarado de um campo composto conta todos os caracteres dos subcampos, incluindo os identificadores e os tamanhos deles. Essa conta aninhada é o erro de implementação mais comum, e é o motivo pelo qual o campo 26 tem tamanho diferente para cada tipo de chave.

Um teto que a tabela de limites esconde

O campo 26 declara o próprio tamanho em dois dígitos, então cabe em 99 caracteres. A chave sozinha pode ter 77 e a descrição 72, mas os dois máximos não podem acontecer juntos. Com uma chave aleatória de 36 caracteres sobram 37 para a descrição. Implementações que truncam cada subcampo pelo limite isolado geram um campo 26 impossível.

Os campos, na ordem

A ordem altera o resultado da verificação de integridade, então ela é literal.

O identificador do arranjo

O subcampo 26.00 leva a string br.gov.bcb.pix, em minúsculas e literal. Existem exemplos públicos, inclusive em bibliotecas conhecidas, escrevendo essa string em maiúsculas. Não copie: qualquer alteração invalida o código.

O identificador da cobrança

O subcampo 62.05 leva o identificador, com até 25 caracteres, apenas letras e dígitos. Na ausência de identificador, o conteúdo é exatamente três asteriscos, e não a omissão do campo. Isso é norma, não convenção.

O valor

O separador decimal é o ponto, sempre com duas casas, sem separador de milhar e sem símbolo de moeda. Valor zero, vazio ou ausente omite o campo 54 inteiro, e é essa omissão que sinaliza cobrança de valor aberto.

A verificação de integridade

É um CRC-16 na variante CCITT-FALSE: polinômio 0x1021, valor inicial 0xFFFF, sem XOR final e sem reflexão de entrada ou de saída. O cálculo cobre a string inteira já com os quatro caracteres 6304 que abrem o próprio campo, e exclui apenas os quatro dígitos do resultado.

O resultado sai como quatro dígitos hexadecimais maiúsculos, com zero à esquerda quando necessário. Um valor escrito como F12 em vez de 0F12 é recusado.

As seis armadilhas

Não incluir o 6304 no cálculo. Usar 0x0000 como valor inicial. Aplicar um XOR final. Escolher CRC-16 nas variantes ARC ou MODBUS. Gerar o hexadecimal em minúsculas, que alguns bancos aceitam e outros recusam. Perder o zero à esquerda. Cada uma produz um código que parece correto e não funciona.

Vetores de teste

As quatro strings abaixo são geradas nesta build pelo mesmo código que roda no gerador. Se a sua implementação não reproduzi-las caractere por caractere com as mesmas entradas, ela está errada.

00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***6304F012

00020126330014br.gov.bcb.pix011112345678909520400005303986540550.005802BR5913PADARIA DO ZE6009SAO PAULO62070503***63046398

[email protected] 4252040000530398654071234.565802BR5913LOJA ACAO CIA6007NITEROI62090505PED426304D41E

00020126360014br.gov.bcb.pix0114+552199999888852040000530398654040.015802BR5913SERVICOS LTDA6014RIO DE JANEIRO62070503***6304BC81

Repare no terceiro: o e comercial sumiu do nome, o acento de Niterói saiu e a descrição foi maiusculizada. O padrão admite um conjunto maior de caracteres, mas o comportamento com acento e símbolo varia entre bancos, então tratamos o texto antes de montar.

O que este formato não faz

Não existe Pix dinâmico sem servidor. Um código dinâmico carrega, no subcampo 26.25, o endereço de um payload hospedado e assinado por um prestador de serviço de pagamento, e é ele quem devolve valor, vencimento e status. Um código estático carrega os dados em si mesmo e pode ser pago quantas vezes o pagador quiser.

Também não dá para saber, a partir do código, se a chave existe ou de quem ela é. Essa consulta é feita no DICT, o diretório de chaves do Banco Central, cujo acesso é restrito a instituições autorizadas.