Entendendo o Payload do Pix (Copia e Cola) e gerando um qr-code estático

TL;DR: Este artigo detalha a estrutura do payload Pix (o código do Pix Copia e Cola), que compõe os QR Codes Pix. Vamos explorar cada campo no formato TLV (Tag-Length-Value), explicar sua finalidade, quem o preenche e as diferenças entre QR Codes estáticos e dinâmicos.

---

📋 O que é o “payload” Pix (Pix Copia e Cola)?

O payload Pix é a sequência de caracteres que representa um QR Code do Pix. É o texto que o usuário copia e cola para realizar um pagamento via Pix, contendo todas as informações essenciais para a transação. Este texto segue o padrão BR Code, definido pelo Banco Central do Brasil com base no padrão internacional EMV® QR Code.

Existem dois tipos principais de QR Code Pix:

• Estático: Pode ser reutilizado para múltiplas transações e geralmente utilizado por pessoas físicas, para doações ou pequenos comércios. Pode ter ou não um valor predefinido.
• Dinâmico: Válido para apenas uma transação (tornando-se inválido após o pagamento). É comumente empregado em e-commerce, boletos Pix ou cenários que exigem conciliação automática e informações adicionais do recebedor. O QR dinâmico é gerado via API Pix de um PSP e normalmente contém uma URL que aponta para os detalhes da cobrança.

Ambos os tipos são convertidos em uma imagem de QR Code e geram um código Pix Copia e Cola compatível com qualquer instituição bancária. A principal diferença reside na estrutura interna: o QR dinâmico inclui um link para obter os dados completos da cobrança, enquanto o estático carrega diretamente a chave Pix e os dados básicos do recebedor.

🧾 Exemplo de Payload Pix Estático Completo

A seguir, um exemplo de código Pix Copia e Cola para um pagamento estático fictício. Este QR code possui um valor fixo de R$ 25,75 e utiliza uma chave Pix do tipo CPF. Para facilitar a visualização, inserimos quebras de linha, mas no código real, é um único bloco de texto contínuo.

000201
26330014BR.GOV.BCB.PIX011111223344556
52040000
5303986
540525.75
5802BR
5909ANA SILVA
6014BELO HORIZONTE
62070503***
6304BB4A

(Os trechos acima são separados por quebras de linha para legibilidade; no payload real, eles são contíguos.)

Este payload seria gerado para ANA SILVA, residente em BELO HORIZONTE, cobrando R$ 25,75, utilizando a chave Pix fictícia CPF 112.233.445-56. Agora, vamos destrinchar cada parte desse código.

---

🔍 Explicação Campo a Campo (TLV)

O padrão EMV QR Code organiza os dados no formato TLV (Tag-Length-Value), que significa Identificador + Tamanho + Valor. Cada campo possui um ID (tag numérica de dois dígitos), seguido por dois dígitos que informam o comprimento do valor em caracteres, e, por fim, o valor em si.

Analisaremos os campos na ordem em que aparecem no payload:

🔹 000201 (Payload Format Indicator)

• ID 00 – Payload Format Indicator (Indicador de Formato do Payload).
• Valor: 01 (formato EMV versão 01).
• Por que existe: Garante que os aplicativos bancários identifiquem corretamente o padrão do QR Code (EMV Pix v1).
• Quem preenche: É um valor fixo do padrão. Todo payload Pix válido deve começar com 000201.

🔹 010211 (Point of Initiation Method – Opcional)

• Observação: No exemplo acima, o ID 01 não está explicitamente presente, pois é opcional no QR estático. No entanto, é crucial entender sua função.
• ID 01 – Point of Initiation Method (Ponto de Iniciação).
• Valor: 11 para QR Code estático, 12 para QR Code dinâmico.
• Por que existe: Faz parte do padrão EMV e informa se o QR Code é de uso único ou múltiplo. Isso ajuda o aplicativo pagador a tratar o código adequadamente (por exemplo, alertar se um QR dinâmico já foi pago).
• Quem preenche: Gerado automaticamente pela aplicação. Em Pix estático, pode ser omitido (equivalente a 11). Em Pix dinâmico, deve ser incluído com valor 12.

🔹 2633... (Merchant Account Information – Pix)

Este é um campo composto que identifica a conta do recebedor. No nosso exemplo, ele começa com 26 (o ID do campo de Merchant Account Information) e tem um comprimento de 33 caracteres, englobando todos os subcampos internos.

• ID 26 – Merchant Account Information - Pix. Indica que os próximos subcampos se referem ao arranjo de pagamento Pix.

Dentro do campo 26, existem dois subcampos cruciais:

🔹 Subcampo 0014BR.GOV.BCB.PIX (GUI – Identificador do arranjo Pix)

• ID do subcampo: 00 (GUI – Globally Unique Identifier) do arranjo Pix.
• Tamanho: 14 (14 caracteres).
• Valor: BR.GOV.BCB.PIX (domínio do Pix no Bacen).
• Por que existe: Identifica globalmente o arranjo de pagamento como Pix do Banco Central do Brasil. É fundamental para que os aplicativos reconheçam e interpretem corretamente os demais subcampos.
• Quem preenche: É um valor fixo pelo padrão Pix. Deve ser sempre BR.GOV.BCB.PIX.

🔹 Subcampo 011111223344556 (Chave Pix do recebedor)

• ID do subcampo: 01 (identificador da conta, que no Pix significa chave Pix).
• Tamanho: 11 (11 caracteres).
• Valor: 11223344556 (a chave Pix em si, no nosso caso, um CPF fictício).
• Tipos de Chave Pix: Pode ser CPF/CNPJ (apenas dígitos), telefone celular (formato internacional), e-mail (formato usual) ou EVP (chave aleatória, um UUID). O CPF no exemplo (11223344556) tem 11 dígitos, por isso o tamanho 11.
• Importante: A chave não contém formatação (pontos, traços); o aplicativo pagador geralmente a formata para exibição.
• Por que existe: É o dado mínimo para direcionar o pagamento. O DICT (Diretório de Identificadores de Contas Transacionais) do Bacen mapeia essa chave para os dados bancários do recebedor (ISPB, agência, conta), eliminando a necessidade de exibir essas informações no QR estático.
• Quem preenche: Quem gera o QR code. Deve ser uma chave Pix válida e cadastrada.
• Diferença para QR Dinâmico: No Pix dinâmico, este subcampo 01 não é usado. Em seu lugar, o QR dinâmico contém o subcampo 25, que armazena uma URL para obter os detalhes da cobrança.

🔹 52040000 (Merchant Category Code)

• ID 52 – Merchant Category Code (MCC).
• Valor: 0000 (código de categoria genérico).
• Por que existe: Identifica a categoria do estabelecimento comercial (padrão ISO 18245). No Pix, 0000 é frequentemente usado para uma categoria não especificada, pois o Pix é de uso amplo.
• Quem preenche: Normalmente fixo como 0000 em QRs Pix, a menos que a solução geradora precise informar um MCC específico.

🔹 5303986 (Transaction Currency)

• ID 53 – Código da Moeda da Transação.
• Valor: 986 (código ISO 4217 para o Real brasileiro - BRL).
• Por que existe: Permite que o QR code especifique a moeda. No Pix, sempre será Real brasileiro.
• Quem preenche: Fixo: usar 986 para Pix no Brasil.

🔹 540525.75 (Transaction Amount)

• ID 54 – Valor da transação (Amount).
• Valor: 25.75 (representando R$ 25,75). O comprimento 05 indica 5 caracteres, incluindo o ponto decimal.
• Valor em Aberto: Se o campo 54 for omitido, o QR Code estático permite valor em aberto, ou seja, o pagador digitará o valor que desejar pagar. Isso é comum em doações ou quando o recebedor insere o valor manualmente.
• Por que existe: Possibilita QR Codes de cobrança com valor pré-definido, facilitando para o pagador e garantindo o montante correto para o recebedor.
• Quem preenche: Você (ou sua aplicação), caso queira um valor fixo. O formato deve ser numérico com ponto decimal separando reais e centavos (ex: 0.50, 15.00, 123.99). Para valor em aberto, omita o ID 54.

🔹 5802BR (Country Code)

• ID 58 – Código do País.
• Valor: BR (Brasil).
• Por que existe: É obrigatório pelo padrão EMV para informar o país da transação, garantindo compatibilidade.
• Quem preenche: Fixo: BR para pagamentos Pix no Brasil.

🔹 5909ANA SILVA (Merchant Name)

• ID 59 – Nome do recebedor (Merchant Name).
• Valor: ANA SILVA (9 caracteres).
• Importante: Não utilize acentos ou caracteres especiais; siga o padrão ASCII simples. ANA SILVA está em letras maiúsculas e sem acentos.
• Limite: Permite até 25 caracteres.
• Por que existe: Para exibir ao pagador, no aplicativo, quem está recebendo o dinheiro, servindo como uma confirmação visual da transação.
• Quem preenche: Geralmente quem gera o QR. Idealmente, deve ser o nome cadastrado na chave Pix para evitar divergências, utilizando caixa alta e sem caracteres especiais.

🔹 6014BELO HORIZONTE (Merchant City)

• ID 60 – Cidade do recebedor (Merchant City).

• Valor: BELO HORIZONTE (14 caracteres). Novamente, sem acentos.

• Limite: Permite até 15 caracteres.

• Por que existe: Requisito do padrão EMV. No Pix, costuma-se usar a cidade de domicílio do recebedor.

• Quem preenche: Você (ou o sistema gerador). É obrigatório no payload para máxima compatibilidade com aplicativos. Use caixa alta e sem caracteres especiais.

• Postal Code (ID 61) – Opcional: O padrão EMV também define um campo 61 para CEP (código postal). No Pix, é opcional e pouco usado em QRs estáticos comuns. Se incluído, seriam 8 dígitos (ex: 01012000) precedidos de 6108.

🔹 6207... (Additional Data Field Template)

O ID 62 indica o template de dados adicionais, sendo um campo composto que contém subcampos. Aqui podem entrar informações extras como o identificador da transação (TXID) ou um campo livre de referência.

No nosso exemplo, temos 62070503***:

🔹 Subcampo 0503*** (Transaction ID – TXID)

• ID do subcampo: 05 (Referência da transação - TXID).

• Tamanho: 03 (3 caracteres).

• Valor: *** (indicador de ausência de TXID específico).

• Finalidade: Em Pix estático, o TXID pode ser usado pelo recebedor para identificar pagamentos e conciliar. Permite até 25 caracteres alfanuméricos. O valor *** é uma convenção do Bacen para indicar que não há TXID definido.

• Por que existe: Permite ao recebedor conciliar pagamentos. No Pix dinâmico, o TXID é obrigatório e único por cobrança; no estático, serve como referência opcional de livre uso.

• Quem preenche: Você, ao gerar o QR. Se não for usar um identificador, o padrão recomenda *** para explicitar a ausência.

• Campos adicionais opcionais no ID 62:

  • Subcampo 02 – Informação Adicional ao Pagador: Um campo livre para incluir uma mensagem ou descrição para o pagador, com até 72 caracteres. Em QRs dinâmicos, é preenchido com a descrição (solicitacaoPagador).
  • Subcampo 03 – Campo fss (Facilitador de Saque): Usado apenas para Pix Saque/Troco, contendo o ISPB do facilitador. Não é comum em Pix padrão.

🔹 6304BB4A (CRC16)

• ID 63 – Checksum CRC16.
• Valor: BB4A (código de 4 caracteres hexadecimais).
• Cálculo: Os últimos 4 caracteres do payload são o valor do CRC16 (16-bit Cyclic Redundancy Check) calculado sobre todo o conteúdo anterior do payload, incluindo IDs, tamanhos e valores, até o byte anterior ao próprio campo 63. O padrão é o CRC-16/CCITT-FALSE com polinômio 0x1021 e valor inicial 0xFFFF.
• Por que existe: Para garantir a integridade do código. Se qualquer caractere do payload for alterado, o CRC calculado não irá coincidir, e o aplicativo pagador identificará o QR Code como corrompido ou inválido, evitando pagamentos incorretos.
• Quem preenche: É calculado automaticamente pela ferramenta ou biblioteca que gera o QR.

---

🟣 E o QR Code Dinâmico? (Pix com URL)

O Pix dinâmico possui algumas diferenças importantes na composição do payload:

• O campo 01 (Point of Initiation Method) aparece com valor 12 obrigatoriamente, indicando uso único. O payload iniciaria com 000201010212....
• No campo 26 (Merchant Account Info), em vez do subcampo 01 (chave Pix), utiliza-se o subcampo 25 para a URL do payload. Essa URL é fornecida pelo PSP que criou a cobrança via API Pix e aponta para um endpoint do PSP recebedor contendo os detalhes da transação em formato JSON Web Token.
• Os campos 54 (valor) e 62-05 (TXID) podem até constar no payload dinâmico, mas são ignorados pelo aplicativo pagador, que utilizará os dados obtidos via URL/API. O manual sugere que esses campos não sejam preenchidos no QR dinâmico, pois o valor e o TXID verdadeiros vêm do payload JSON da cobrança.
• Os demais campos (52, 53, 58, 59, 60, 63 – MCC, moeda, país, nome, cidade, CRC) mantêm funções similares.

Exemplo ilustrativo de Pix Dinâmico:

000201010212
26900014BR.GOV.BCB.PIX2568https://pix.meubanco.com.br/qr/xyz789abcd...
5204000053039865802BR5912LOJA EXEMPLO6009SAO PAULO6304XXXX

Observe o 010212 após o início, e dentro do 26, a presença do subcampo 25 com a URL. O aplicativo, ao ler este código, fará uma chamada a essa URL para obter as informações completas da cobrança (valor, TXID, descrição) antes de finalizar o pagamento.

Em resumo, o QR dinâmico oferece funcionalidades mais complexas como vencimento, multa e uso único com confirmação, enquanto o QR estático é mais simples e pode ser gerado offline sem chamadas à API Pix.

---

💻 Gerando o payload.

Caso queira criar seu payload pix, tanto o qr-code quando o copia-e-cola, sinta-se livre para usar esse projeto de geração, o QR-pix-off.

QR-pix-off é uma ferramenta Python minimalista para a geração offline de QR Codes Pix Estáticos e seus respectivos payloads "Copia e Cola".

https://github.com/usrbinbrain/QR-pix-off