Por que o QR Code Pix é recusado: o CRC inclui o 6304
O sintoma é sempre o mesmo e é o pior possível: o QR Code é gerado, a câmera lê, o aplicativo do banco abre com o nome e o valor certos — e recusa. Nada no código parece errado, porque quase nada está. O que costuma estar errado é o checksum, e quase sempre por um único detalhe.
A regra, em uma frase
O CRC do BR Code é calculado sobre o payload inteiro incluindo o "6304" que introduz o próprio checksum, e excluindo apenas os quatro caracteres do valor dele.
Não é uma peculiaridade do Pix. O BR Code segue o padrão EMV de QR Code para pagamentos, e a especificação diz que o cálculo cobre todos os objetos de dados na ordem em que aparecem, mais o identificador e o tamanho do próprio CRC. O identificador é 63 e o tamanho é 04 — daí o "6304" entrar na conta.
Por que é tão fácil errar
Porque a intuição diz o contrário. Um checksum normalmente cobre os dados e não a si mesmo, então parar antes do campo 63 inteiro parece o mais natural. O resultado é um payload perfeitamente bem formado com quatro caracteres finais errados.
E porque o erro não aparece em nenhum dos lugares onde se costuma testar. O QR é gerado sem reclamação, qualquer leitor de código o decodifica, o texto do copia e cola parece correto, os campos estão todos lá. A validação só acontece no fim da linha, dentro do aplicativo do banco, quando já não há como saber em que etapa a coisa quebrou.
O vetor de teste
A forma mais rápida de resolver a dúvida é rodar a sua função contra um payload cujo checksum é publicado por quem define o padrão. O manual do BR Code do Banco Central traz um exemplo completo terminado em 6304AD38. Calcule o CRC sobre esse payload sem os quatro últimos caracteres — ou seja, mantendo o 6304 no fim da entrada — e o resultado tem de ser AD38.
Se a sua implementação devolver 50D3, está calculando o CRC sem o 6304. Esse é exatamente o erro, e é o valor que sai quando se corta o campo 63 inteiro em vez de só o valor dele.
entrada termina em …6304 → AD38Correto: o identificador e o tamanho entram no cálculo.entrada termina antes do 6304 → 50D3Errado: gera um QR que lê e não paga.
Os parâmetros do algoritmo
O CRC é o CRC-16/CCITT-FALSE: polinômio 0x1021, valor inicial 0xFFFF, sem reflexão de entrada ou saída e sem XOR final. O resultado vai no payload como quatro caracteres hexadecimais maiúsculos, com zero à esquerda quando necessário.
Vale conferir a implementação com o vetor canônico dessa variante antes de olhar para o Pix: o CRC-16/CCITT-FALSE da cadeia 123456789 é 29B1. Se a sua função não devolver isso, o problema não está no 6304 e sim nos parâmetros — quase sempre reflexão ligada por engano, que é o que distingue essa variante das outras do mesmo polinômio.
CRC-16/CCITT-FALSE de 12345678929B1. Se der outro valor, os parâmetros estão errados.
Se o CRC está certo e ainda recusa
Descartado o checksum, as causas seguintes são quase sempre de tamanho e de conteúdo dos campos, não de cálculo.
- O campo 26 tem limite de 99 caracteres no total, incluindo o GUI e a chave. Uma descrição longa demais estoura esse limite sem aviso.
- O nome do recebedor tem 25 caracteres e a cidade 15. Textos maiores precisam ser cortados, e acentos costumam ser recusados: use apenas ASCII, em maiúsculas.
- O valor vai como número decimal com ponto, nunca formatado para leitura. Se não houver valor definido, o campo 54 deve ser omitido, e não enviado como zero.
- O identificador no campo 62 aceita apenas letras e números, até 25 caracteres. Quando não há identificador, o padrão é ***.
- Cada objeto declara o próprio tamanho em dois dígitos. Um tamanho que não corresponde ao conteúdo desalinha tudo o que vem depois, e o erro aparece longe da origem.
Conferir o seu código agora
O gerador de QR Code Pix do nTools monta o payload no seu próprio navegador e calcula o CRC pela regra acima. Serve para comparar: gere um código com a sua chave e confira campo a campo contra o que o seu sistema produz. A chave, o nome e o valor não são enviados para o nTools nem para banco nenhum.
Referência: Manual do BR Code, Banco Central do Brasil, e o Manual de Padrões para Iniciação do Pix.