Como funciona o QR Code PIX

1. O padrão EMV QRCPS-MPM

O PIX Copia e Cola — aquele texto que começa com 00020101021126… — é a materialização textual do padrão internacional EMV QR Code Specification for Payment Systems — Merchant-Presented Mode (QRCPS-MPM), publicado pela EMVCo (consórcio formado por Europay, MasterCard e Visa). Esse padrão descreve como codificar, dentro de uma única string, todas as informações que um app bancário precisa para iniciar um pagamento: a chave do recebedor, o nome, a cidade, a moeda, o valor e um checksum de integridade.

O Banco Central do Brasil adotou o QRCPS-MPM e publicou o Manual do BR Code, documento normativo que instancia o padrão EMV para o PIX. A adaptação brasileira é estreita: mesma estrutura TLV, mesmos IDs reservados pela EMVCo para uso doméstico (IDs 26–51) e mesmo algoritmo de checksum. A customização está no GUI fixo br.gov.bcb.pix, no uso do código de moeda 986 (BRL da ISO 4217) e no país BR (ISO 3166-1 alpha-2).

2. Estrutura TLV (Tag-Length-Value)

Todo o payload BR Code é uma sequência de campos TLV. Cada campo é formado por três pedaços contíguos:

• Tag (ID) — dois caracteres numéricos que identificam o campo. Ex.: 00, 26, 63.
• Length — dois caracteres numéricos com o tamanho (em bytes ASCII) do valor que vem em seguida.
• Value — o conteúdo do campo, com exatamente o tamanho informado acima.

Exemplo mínimo: o campo Payload Format Indicator (ID 00) tem sempre o valor fixo "01":

ID=00  Length=02  Value=01
→ "000201"

Alguns campos são compostos: seu valor é, ele mesmo, uma sequência de sub-TLVs. É o caso do ID 26 (Merchant Account Information), onde dentro do valor aparecem os sub-IDs 00 (GUI), 01 (chave PIX) e 02 (descrição). Também é composto o ID 62 (Additional Data Field Template), que carrega o sub-ID 05 (Reference Label).

Não existem separadores entre campos: o parser avança lendo a Tag, depois a Length, depois pulando exatamente Length caracteres. Qualquer off-by-one na contagem quebra todo o resto.

3. Campos do payload BR Code

A tabela abaixo lista os campos obrigatórios para um QR PIX estático. Campos marcados como composto têm sub-TLVs dentro do valor.

Detalhe do ID 26 — Merchant Account Information

O campo ID 26 é composto e carrega a identificação do arranjo PIX. Seus sub-TLVs são:

Sub-ID 00  Length=14  Value="br.gov.bcb.pix"   (GUI fixo do PIX)
Sub-ID 01  Length=NN  Value="<chave pix>"        (CPF, CNPJ, e-mail, fone ou EVP)
Sub-ID 02  Length=NN  Value="<descrição>"        (opcional, máx. 25 chars)

O valor final do campo 26 é a concatenação desses três sub-TLVs — e o Length do campo 26 é o tamanho total dessa concatenação. É nesse ponto que a maioria dos geradores caseiros erra: o length precisa ser recalculado sempre que a chave, o GUI ou a descrição mudam.

Detalhe do ID 62 — Additional Data Field Template

Também composto, carrega o sub-ID 05 (Reference Label, conhecido como txid). Em QR estático reutilizável, o padrão é usar ***, indicando que o txid não identifica uma transação específica. Em QR dinâmico, o txid é gerado pelo provedor de serviço de pagamento e tem até 25 caracteres alfanuméricos.

Sub-ID 05  Length=03  Value="***"
→ Campo 62: "62070503***"

4. O algoritmo CRC-16/CCITT-FALSE

O último campo do payload é sempre o ID 63, que carrega quatro caracteres hexadecimais em maiúsculas representando o CRC-16 calculado sobre toda a string anterior acrescida de 6304 (isto é, o Tag e o Length do próprio ID 63, antes de o valor do checksum ser conhecido). Esse detalhe é a parte que mais confunde implementações novas: o CRC protege o ID 63 incluindo seu próprio cabeçalho, mas obviamente não inclui o valor do CRC em si.

Os parâmetros do algoritmo (conforme ISO/IEC 13239) são:

• Polinômio gerador: 0x1021
• Valor inicial: 0xFFFF
• XOR final: 0x0000
• Input refletido: não
• Output refletido: não
• Saída: 4 caracteres hexadecimais em maiúsculas

Pseudocódigo

função crc16ccittFalse(texto):
  crc = 0xFFFF
  para cada caractere c em texto:
    crc = crc XOR (codigoAscii(c) << 8)
    repita 8 vezes:
      se (crc E 0x8000) != 0:
        crc = ((crc << 1) XOR 0x1021)
      senão:
        crc = (crc << 1)
      crc = crc E 0xFFFF      // truncar em 16 bits
  retornar hex(crc).upper().padStart(4, '0')

Se a biblioteca de CRC usada implementar a variante CRC-16/CCITT-TRUE ou a CRC-16/XMODEM, o resultado será diferente e o QR será rejeitado. A única variante aceita pelo BACEN é a FALSE, que usa valor inicial 0xFFFF sem reflexão.

5. Exemplo completo de payload

Vamos montar, passo a passo, o payload para um QR PIX estático com os seguintes dados:

• Chave: 12345678901 (CPF)
• Nome: FULANO DE TAL
• Cidade: SAO PAULO
• Valor: R$ 100,00
• Descrição: PAGAMENTO

Passo 1 — Montar cada campo

00  Payload Format Indicator:     "000201"
01  Point of Initiation Method:   "010211"                (estático)
26  Merchant Account Information:
      00 GUI:          "0014br.gov.bcb.pix"
      01 Chave (CPF):  "011112345678901"
      02 Descrição:    "0209PAGAMENTO"
    Concatenação interna = "0014br.gov.bcb.pix011112345678901 0209PAGAMENTO"
    Tamanho total = 46 → campo 26 = "2646" + valor
    → "26460014br.gov.bcb.pix0111123456789010209PAGAMENTO"
52  Merchant Category Code:        "52040000"
53  Transaction Currency (BRL):    "5303986"
54  Transaction Amount:            "5406100.00"
58  Country Code (BR):             "5802BR"
59  Merchant Name:                 "5913FULANO DE TAL"
60  Merchant City:                 "6009SAO PAULO"
62  Additional Data Field:         "62070503***"

Passo 2 — Concatenar em ordem e adicionar "6304"

Junte todos os campos do ID 00 ao ID 62 e acrescente a string literal 6304 (Tag + Length do CRC, sem valor ainda):

000201010211
26460014br.gov.bcb.pix0111123456789010209PAGAMENTO
52040000
5303986
5406100.00
5802BR
5913FULANO DE TAL
6009SAO PAULO
62070503***
6304

(As quebras de linha acima são apenas visuais — no payload real tudo é concatenado em uma única linha contínua, sem espaços entre campos.)

Passo 3 — Calcular o CRC-16/CCITT-FALSE sobre a string do passo 2

Aplicando o pseudocódigo da seção anterior sobre a string concatenada (incluindo o 6304 no final), o algoritmo produz um valor hexadecimal de 4 dígitos — por exemplo B1C3. Esse valor varia conforme cada byte do payload, então basta mudar o nome, a cidade ou o valor para obter um CRC diferente.

Passo 4 — Concatenar o CRC ao final

...62070503***6304B1C3

Pronto. Essa string é o PIX Copia e Cola: pode ser colada em qualquer app bancário brasileiro, ou passada diretamente a uma biblioteca de QR Code (no nosso caso, a qrcode no navegador) para gerar a imagem final.

6. Tipos de chave PIX aceitos

O sub-ID 01 do campo 26 carrega a chave PIX do recebedor. O arranjo PIX aceita cinco formatos, cada um com sua validação específica:

O comprimento da chave é informado no sub-Length do sub-ID 01 — e, por ser sub-campo de um campo composto, seu comprimento também precisa ser contabilizado no Length externo do ID 26. Essa aritmética aninhada é o motivo pelo qual o campo 26 tem um tamanho diferente para cada tipo de chave.

7. PIX estático vs dinâmico

O Point of Initiation Method (ID 01) determina se o QR é de uso único ou reutilizável:

• Estático (método 11) — o payload inteiro está dentro da string. Funciona offline, pode ser escaneado por várias pessoas diferentes e é adequado para doações, gorjetas, caixas de coleta, vendas esporádicas e qualquer contexto onde o recebedor não tem backend próprio. É o tipo que geradores client-side como o nosso produzem.
• Dinâmico (método 12) — parte dos dados fica em um servidor do provedor de serviço de pagamento, e o QR carrega um txid que aponta para essa transação específica. Permite cobrança com valor, juros, multa e vencimento definidos por API, além de conciliação automática. Depende de integração backend com uma instituição financeira autorizada pelo BACEN.

Uma pergunta comum: é seguro um QR estático com valor fixo? Sim — a integridade do payload é garantida pelo CRC-16, e o pagador sempre confirma o recebedor e o valor no app antes de concluir o pagamento. O QR estático apenas pré-preenche os campos; ele não autoriza débito sozinho.

8. Fontes oficiais

As regras descritas nesta página não são nossa interpretação: vêm da documentação normativa publicada pelo Banco Central do Brasil e pelas organizações que mantêm os padrões subjacentes. Consulte sempre a fonte primária antes de ir a produção:

• Banco Central do Brasil — Manual do BR Code e especificações do PIX: bcb.gov.br/estabilidadefinanceira/spb_pix. Publicação normativa com os IDs usados, as regras de txid, os tipos de chave aceitos e as regras de integração.
• EMVCo — QR Code Specification for Payment Systems (QRCPS-MPM). Especificação internacional que define a estrutura TLV, os IDs reservados para uso doméstico (26–51) e o algoritmo de checksum. É o documento que o BACEN referencia para instanciar o BR Code.
• ISO/IEC 13239 — padrão que define o CRC-16/CCITT-FALSE usado no campo 63.
• ISO 4217 — código de moeda (986 para BRL).
• ISO 3166-1 alpha-2 — código de país (BR para Brasil).

Esta página é referência técnica para desenvolvedores e para quem quer entender o que acontece por trás do QR Copia e Cola. Não é aconselhamento financeiro nem orientação jurídica sobre pagamentos. Para integrar com o PIX como instituição financeira, consulte diretamente o Banco Central do Brasil.