ISO 8583 Ainda Está em Todo Lugar: Parseando a Mensagem que Move os Trilhos

💡 TL;DR (Too Long; Didn't Read)

ISO 8583 em 90 segundos:

Quando uma transação com chip vai online, ela se torna uma mensagem ISO 8583: um MTI de quatro dígitos, um bitmap e os elementos de dados que o bitmap declara presentes.

O MTI codifica versão, classe da mensagem (autorização, financeira, estorno…), função e quem a originou — quatro dígitos que dizem o que a mensagem é.

O bitmap primário tem 64 bits; bit n ligado significa "o DE n está presente". Bit 1 ligado significa que segue um bitmap secundário para os DEs 65–128. A mensagem é esparsa por desenho.

Cada DE tem tipo e regra de comprimento definidos: fixo, LLVAR (prefixo de comprimento de 2 dígitos) ou LLLVAR (3 dígitos). Erre a regra de comprimento e você dessincroniza o parse inteiro.

É um protocolo dos anos 1980 que ainda carrega a maior parte das autorizações de cartão do mundo. Você vai encontrá-lo.

Existe um mito persistente de que o ISO 8583 é legado no sentido de "acabou". Ele é legado no sentido de "estrutural". A esmagadora maioria das autorizações de cartão da Terra — toda vez que um terminal vai online para uma aprovação — ainda atravessa uma mensagem ISO 8583 em algum ponto entre o adquirente e o emissor, mesmo quando as pontas estão vestidas de APIs JSON. Se você integra com um host adquirente, um switch ou um processador emissor, você vai parsear ISO 8583, e o protocolo recompensa um modelo mental claro porque sua densidade é deliberada: foi desenhado quando cada byte no fio custava dinheiro. Este é um percurso estrutural — o MTI, o bitmap, as regras de comprimento e os elementos de dados que você de fato toca. Segue o ISO 8583:1987/1993/2003; a semântica dos campos varia por bandeira e rede, então trate isto como a gramática e a especificação da sua rede como o dicionário.

A mensagem em três partes

Uma mensagem ISO 8583 é, estruturalmente, três coisas em ordem: um Message Type Indicator, um ou dois bitmaps e uma série de elementos de dados. Essa é a forma inteira. Tudo que é difícil no ISO 8583 está nos detalhes de cada parte, não no arranjo.

O MTI: que tipo de mensagem é esta

O MTI são quatro dígitos, e cada dígito é uma coordenada. O primeiro é a versão (0 = 1987, 1 = 1993, 2 = 2003, 8 = específica da rede). O segundo é a classe da mensagem: 1xx autorização, 2xx financeira (com lançamento monetário), 4xx estorno, 8xx gerenciamento de rede, e assim por diante. O terceiro é a função — requisição, resposta de requisição, aviso, resposta de aviso — e o quarto é a origem (adquirente, emissor, outro). Então um MTI 0100 se lê como: versão 1987, classe autorização, requisição, do adquirente. Sua resposta é 0110. Um 0400 é uma requisição de estorno; um 0800 é uma mensagem de gerenciamento de rede, como um sign-on ou um teste de eco.

Aprenda a ler o MTI de relance e você sabe, antes de parsear um único campo, se está olhando uma autorização ou um estorno, uma requisição ou uma resposta, e qual lado enviou. Esse enquadramento previne o erro clássico de aplicar lógica de autorização a um estorno porque você não checou a classe.

O bitmap: quais campos estão presentes

O ISO 8583 não envia campos vazios. Ele envia um bitmap — um mapa de 64 bits em que o bit n ligado significa "o elemento de dados n está presente nesta mensagem". A mensagem então contém exatamente esses DEs, em ordem crescente. É por isso que o protocolo é compacto: uma mensagem que usa quinze campos carrega quinze campos, não cento e vinte e oito espaços reservados.

Há uma recursão para internalizar. O bit 1 do bitmap primário não é o DE 1 — é o sinalizador "segue um bitmap secundário". Se o bit 1 está ligado, os próximos 64 bits são o bitmap secundário cobrindo os DEs 65 a 128. Então o parse é: leia o bitmap primário; se seu bit mais alto estiver ligado, leia o bitmap secundário; depois percorra os bits combinados em ordem e, para cada bit ligado, leia aquele DE conforme seu tipo. Bitmaps são normalmente transmitidos como hexadecimal (8 bytes cada). Um bitmap primário 7220000000000000 tem os bits 2, 3, 4, 7, 11, 12… ligados — decodifique-o e você tem a lista de campos da mensagem antes de ler um único valor.

Fixo, LLVAR, LLLVAR: a regra de comprimento que te mantém sincronizado

Cada elemento de dados tem formato e disciplina de comprimento definidos, e errar isso é como parsers dessincronizam. Três formas de comprimento cobrem a maioria dos campos:

Fixo — o campo tem exatamente N caracteres/dígitos, sem prefixo de comprimento. O DE 3 (processing code) é fixo de 6 dígitos; o DE 11 (STAN) é fixo de 6.
LLVAR — um prefixo de comprimento de 2 dígitos dá o comprimento do campo, e então esse número de caracteres segue. Usado para campos que variam mas ficam abaixo de 100, como o DE 2 (PAN): o LL diz quantos dígitos de PAN seguem.
LLLVAR — um prefixo de comprimento de 3 dígitos, para campos de até 999. O DE 55 (dados do ICC) é LLLVAR porque a sopa de tags EMV dentro dele pode ser grande.

O modo de falha é implacável: leia um campo LLVAR como fixo, ou interprete mal seu prefixo de comprimento, e todo byte depois dele desloca — você vai parsear os dados do campo seguinte como um comprimento, obter uma contagem sem sentido e produzir lixo que parece estruturado. Um parser robusto é orientado por tabela: uma definição por DE de tipo, forma de comprimento e comprimento máximo, aplicada na ordem do bitmap. Não escreva os offsets à mão.

Os elementos de dados que você realmente encontra

Há 128 DEs possíveis; você vai tocar regularmente talvez duas dúzias. Os que vale conhecer por número:

DE 2 — Primary Account Number (LLVAR).
DE 3 — Processing Code (6 dígitos: tipo de transação + tipos de conta).
DE 4 — Valor da transação (fixo de 12, em unidades menores).
DE 7 — Data e hora de transmissão.
DE 11 — System Trace Audit Number (STAN) — o id de rastreio por mensagem.
DE 12 / 13 — hora / data local da transação.
DE 22 — POS entry mode (como o PAN foi capturado: chip, contactless, tarja, digitado).
DE 24 — código de função / identificador internacional de rede.
DE 25 — POS condition code.
DE 35 — dados da Trilha 2 (LLVAR) — o campo do artigo da Trilha 2.
DE 37 — Retrieval Reference Number (RRN).
DE 38 — identificação de autorização na resposta (o código de aprovação).
DE 39 — código de resposta (o resultado aprova/recusa — 00 é aprovado).
DE 41 / 42 — ID do terminal / ID do estabelecimento.
DE 49 — código da moeda da transação (ISO 4217).
DE 52 — dados de PIN (o PIN block).
DE 55 — dados do ICC (a ponte EMV, LLLVAR).
DE 64 / 128 — Message Authentication Code.

Leia uma mensagem e a história está toda ali: DE 2 quem, DE 4 quanto, DE 49 em qual moeda, DE 22 como foi capturado, DE 39 o que o emissor disse, DE 55 a prova criptográfica do chip.

Cicatrizes de batalha

A resposta ecoa e então difere. Uma resposta 0110 espelha muitos campos da requisição 0100 — STAN, RRN, valor — que é como você as correlaciona. Mas ela adiciona a resposta: DE 39 (código de resposta) e DE 38 (código de autorização). Casar uma resposta com sua requisição por STAN + terminal é a espinha dorsal de qualquer reconciliação, e um STAN duplicado é a espinha dorsal de qualquer disputa.

O bit 1 do bitmap é a recursão, não um campo. O bug de primeiro parse mais comum é tratar o bit mais alto do bitmap primário como "DE 1 presente" e então ler os 8 bytes do bitmap secundário como dados de campo. Se seu primeiro elemento de dados sai como absurdo, cheque se você consumiu o bitmap secundário.

Valores vêm em unidades menores, sem decimal. O DE 4 carrega o valor como inteiro na unidade menor da moeda — 000000010000 com DE 49 = 986 (BRL) são 100,00 reais, não 10000. O expoente vive na tabela de moedas, não na mensagem. Divida pela potência de dez errada e você errou por ordens de magnitude no único campo que ninguém perdoa.

Onde isto se encaixa

O ISO 8583 é o envelope em que o caminho online do fluxo da transação viaja — ele carrega os dados da Trilha 2 (DE 35), o PIN block (DE 52) e, crucialmente, o criptograma EMV e suas tags de apoio (DE 55). O Parser ISO 8583 do gsstk transforma uma mensagem crua em MTI + bitmap + DEs decodificados para você parar de contar prefixos de comprimento à mão.

Leitura Relacionada no gsstk

Campo 55: A Ponte EMV Dentro do ISO 8583 — os dados do chip que viajam no DE 55.
Trilha 2 e o Service Code — o que viaja como DE 35.
PIN Blocks Explicados: Formatos 0 a 4 da ISO 9564 — o que viaja como DE 52.

Ferramentas: parseie uma mensagem com o Parser ISO 8583; decodifique as tags EMV do DE 55 no Dicionário de Tags EMV.

Arquivado em: ISO 8583 · Payments · Acquiring · EMV

Este artigo foi arquitetado por humanos e sintetizado com assistência de IA sob a persona Hephaestus (AI).