Como Decodificar Pix Copia e Cola

O Pix Copia e Cola é um formato prático que permite aos usuários realizar pagamentos instantâneos copiando e colando uma string alfanumérica. Mas você sabia que esse formato segue um padrão internacional chamado EMV QR Code definido pela Europay, Mastercard e Visa, e adaptado pelo Banco Central do Brasil?

Neste artigo, vamos analisar como a string do Pix é estruturada no formato TLV (Tag-Length-Value), aprender a ler os dados do recebedor e valor programaticamente e entender como calcular e recalcular o checksum de segurança CRC16.

1. A Estrutura EMV TLV (Tag-Length-Value)

O padrão do Pix Copia e Cola organiza seus dados em pequenos blocos sequenciais onde cada campo é composto por três partes:

1. Tag (2 dígitos): Identificador do campo (ex: 00 representa o formato, 54 representa o valor).
2. Length (2 dígitos): O tamanho exato do valor em quantidade de caracteres.
3. Value (Variável): Os dados do campo correspondente.

Por exemplo, a string inicial 000201 significa:

• Tag: 00
• Length: 02
• Value: 01

2. Tags Principais do Pix

O Banco Central mapeou dados específicos em tags do padrão EMV:

• Tag 00 (Payload Format Indicator): Sempre fixo como 01 (resultando em 000201).
• Tag 26 (Merchant Account Information - Pix): Um campo complexo (sub-TLV) contendo a chave Pix do recebedor na subtag 01 e, em boletos dinâmicos, a URL do banco na subtag 25.
• Tag 52 (Merchant Category Code): Sempre 0000.
• Tag 53 (Transaction Currency): Código ISO da moeda (986 para o Real brasileiro).
• Tag 54 (Transaction Amount): O valor do Pix (ex: 540510.50 representa R$ 10,50). Omissa em boletos de valor variável definidos pelo pagador.
• Tag 58 (Country Code): Código do país (BR).
• Tag 59 (Merchant Name): Nome completo do recebedor (com limite de 25 caracteres).
• Tag 60 (Merchant City): Cidade do recebedor (com limite de 15 caracteres).
• Tag 62 (Additional Data Field): Sub-TLV contendo o ID da transação (txid) na subtag 05.
• Tag 63 (CRC16 Checksum): É o campo de integridade. Sempre tem a estrutura 6304 seguida pelo hash hexadecimal de 4 dígitos (ex: 6304D1B2) calculados a partir de todo o payload anterior.

3. Calculando o Checksum CRC16

O CRC16 garante que a string não foi alterada ou corrompida. O algoritmo utilizado é o CRC-16 CCITT com o polinômio 0x1021, valor inicial 0xFFFF, sem reversão de bits no input ou no output. Toda vez que você altera o valor da Tag 54, você é obrigado a reconstruir o payload e recalcular o CRC16 correspondente, caso contrário o aplicativo do banco rejeitará o Pix como corrompido.

4. Implementação em Python

Abaixo está um script em Python para fazer o parse básico e calcular o CRC16 de um Pix Copia e Cola:

def calcular_crc16(data: str) -> str:
    crc = 0xFFFF
    polynomial = 0x1021
    for char in data:
        b = ord(char)
        for j in range(8):
            bit = ((b >> (7 - j)) & 1) == 1
            c15 = ((crc >> 15) & 1) == 1
            crc <<= 1
            if c15 != bit:
                crc ^= polynomial
    crc &= 0xFFFF
    return f"{crc:04X}"

# Exemplo de uso:
payload_sem_crc = "00020101021226580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5913DevThru Ltda6009Sao Paulo62070503***6304"
crc = calcular_crc16(payload_sem_crc)
print("CRC16:", crc) # Exemplo de retorno: D1B2
print("Pix Final:", payload_sem_crc + crc)

Erros Comuns na Integração do Pix

1. Caracteres Especiais no Nome: A Tag 59 (Merchant Name) e 60 (Merchant City) não devem conter acentos ou caracteres especiais (ex: substituia ã por a, ç por c). A acentuação pode estourar o tamanho do byte do length e invalidar o parser do app do banco.
2. Não respeitar o limite de tamanho: O nome do recebedor tem limite de 25 caracteres. Se passar disso, o banco costuma rejeitar a transferência.
3. Ignorar o recálculo do Checksum: Alterar o valor direto na string de texto sem calcular o CRC16 correspondente fará o Pix falhar na leitura do aplicativo do banco.