Desafio 04: ISO 8583 — Mensagens Binárias de Autorização Financeira

🇧🇷 Simulador de Mensagens Financeiras Binárias
🇬🇧 ISO 8583 Financial Message Simulator

---

O ISO 8583 é o padrão internacional para mensagens de transações com cartão. É o protocolo que conecta maquininhas (POS), adquirentes (Cielo, Rede, Stone), bandeiras (Visa, Mastercard) e bancos emissores. Todo swipe, tap ou inserção de chip passa por ISO 8583.

Switch: TypeScript vs Go

O que é ISO 8583?

Característica	Descrição
Binário	Dados em bytes, não JSON/XML
TCP puro	Sem HTTP, sem overhead
Bitmaps	Indicam quais campos estão presentes
Baixa latência	Milissegundos por transação
MAC/Criptografia	3DES, AES, RSA
Conexões persistentes	Sessões longas

Estrutura de uma Mensagem ISO 8583

┌─────────────┬──────────────┬────────────────┬──────────┐
│  MTI (4B)   │ Bitmap (8B)  │ Data Elements  │ MAC (8B) │
│  ASCII      │  Primary     │  Variável      │ Binário  │
└─────────────┴──────────────┴────────────────┴──────────┘

Componente	Tamanho	Descrição
MTI	4 bytes	Message Type Indicator (0100, 0200, etc)
Bitmap	8 ou 16 bytes	Bits indicando DEs presentes
Data Elements	Variável	Campos de dados (PAN, valor, etc)
MAC	8 bytes	Message Authentication Code

MTIs Principais

MTI	Nome	Uso
0100/0110	Authorization Request/Response	Pré-autorização
0200/0210	Financial Request/Response	Compra efetiva
0400/0410	Reversal Request/Response	Cancelamento
0800/0810	Network Management Request/Response	Heartbeat, login

Bitmaps: O Coração do ISO 8583

O bitmap é uma sequência de bits que indica quais Data Elements (DE) estão presentes. Se o bit N está setado (1), o DE-N está presente.

Bit	DE	Nome
2	DE-2	PAN (número do cartão)
3	DE-3	Processing Code
4	DE-4	Amount Transaction
7	DE-7	Date/Time
11	DE-11	STAN
14	DE-14	Date Expiration
22	DE-22	POS Entry Mode
35	DE-35	Track 2 Data
38	DE-38	Auth ID Response
39	DE-39	Response Code
41	DE-41	Terminal ID
42	DE-42	Merchant ID
52	DE-52	PIN Data
55	DE-55	ICC Data (EMV)

Arquitetura do Simulador

Message Parser e Builder

export class ISO8583Message {
  public mti: string;
  public bitmap: Bitmap;
  public dataElements: Map<number, DataElement>;

  constructor(mti: string) {
    this.mti = mti;
    this.bitmap = new Bitmap();
    this.dataElements = new Map();
  }

  public setDE(de: number, value: any, type: DataElementType): void {
    if (de > 64) this.bitmap.set(1);
    this.bitmap.set(de);
    this.dataElements.set(de, new DataElement(de, value, type));
  }

  public hasDE(de: number): boolean {
    return this.bitmap.isSet(de);
  }

  public toBuffer(): Buffer {
    const parts: Buffer[] = [];
    parts.push(Buffer.from(this.mti, 'ascii'));
    parts.push(this.bitmap.toPrimaryBuffer());
    if (this.bitmap.isSet(1)) parts.push(this.bitmap.toSecondaryBuffer());

    const sortedDEs = Array.from(this.dataElements.keys()).sort((a, b) => a - b);
    for (const de of sortedDEs) {
      parts.push(this.dataElements.get(de)!.toBuffer());
    }
    return Buffer.concat(parts);
  }

  public static fromBuffer(buffer: Buffer): ISO8583Message {
    let offset = 0;
    const mti = buffer.slice(offset, offset + 4).toString('ascii');
    offset += 4;

    const message = new ISO8583Message(mti);
    const primaryBitmap = buffer.slice(offset, offset + 8);
    message.bitmap.fromPrimaryBuffer(primaryBitmap);
    offset += 8;

    if (message.bitmap.isSet(1)) {
      const secondaryBitmap = buffer.slice(offset, offset + 8);
      message.bitmap.fromSecondaryBuffer(secondaryBitmap);
      offset += 8;
    }

    for (const de of message.bitmap.getSetBits().filter(b => b > 1)) {
      const type = DataElement.getTypeForDE(de);
      const element = DataElement.fromBuffer(buffer, offset, de, type);
      message.dataElements.set(de, element);
      offset += element.getByteLength();
    }
    return message;
  }
}

Bitmap — Manipulação de Bits

export class Bitmap {
  private primary: bigint;
  private secondary: bigint;

  public set(bit: number): void {
    if (bit <= 64) {
      const position = BigInt(64 - bit);
      this.primary |= (1n << position);
    } else {
      const position = BigInt(128 - bit);
      this.secondary |= (1n << position);
    }
  }

  public isSet(bit: number): boolean {
    if (bit <= 64) {
      return (this.primary & (1n << BigInt(64 - bit))) !== 0n;
    }
    return (this.secondary & (1n << BigInt(128 - bit))) !== 0n;
  }

  public toPrimaryBuffer(): Buffer {
    const buffer = Buffer.alloc(8);
    buffer.writeBigUInt64BE(this.primary);
    return buffer;
  }

  public getSetBits(): number[] {
    const bits: number[] = [];
    for (let i = 1; i <= 64; i++) {
      if (this.isSet(i)) bits.push(i);
    }
    if (this.isSet(1)) {
      for (let i = 65; i <= 128; i++) {
        if (this.isSet(i)) bits.push(i);
      }
    }
    return bits;
  }
}

Data Elements — Tipos de Campos

export enum DataElementType {
  FIXED = 'FIXED',
  LLVAR = 'LLVAR',
  LLLVAR = 'LLLVAR',
}

export class DataElement {
  public static getTypeForDE(de: number): DataElementType {
    const spec = ISO8583Spec.getDESpec(de);
    return spec.type;
  }

  public toBuffer(): Buffer {
    const spec = ISO8583Spec.getDESpec(this.de);
    switch (this.type) {
      case DataElementType.FIXED:
        return Buffer.from(String(this.value).padStart(spec.length, '0'), 'ascii');
      case DataElementType.LLVAR: {
        const len = String(this.value).length.toString().padStart(2, '0');
        return Buffer.from(len + this.value, 'ascii');
      }
      case DataElementType.LLLVAR: {
        const len = String(this.value).length.toString().padStart(3, '0');
        return Buffer.from(len + this.value, 'ascii');
      }
    }
  }
}

TCP Server — Comunicação de Baixo Nível

import * as net from 'net';

export class ISO8583TCPServer {
  private server: net.Server;
  private connections: Map<string, net.Socket> = new Map();

  public start(): Promise<void> {
    return new Promise((resolve) => {
      this.server = net.createServer((socket) => this.handleConnection(socket));
      this.server.listen(this.config.port, this.config.host, resolve);
    });
  }

  private handleConnection(socket: net.Socket): void {
    const connectionId = `${socket.remoteAddress}:${socket.remotePort}`;
    this.connections.set(connectionId, socket);

    let messageBuffer = Buffer.alloc(0);

    socket.on('data', (data) => {
      messageBuffer = Buffer.concat([messageBuffer, data]);

      while (messageBuffer.length > 0) {
        const msgLength = messageBuffer.readUInt16BE(0);
        if (messageBuffer.length < 2 + msgLength) break;

        const msgData = messageBuffer.slice(2, 2 + msgLength);
        messageBuffer = messageBuffer.slice(2 + msgLength);

        const isoMessage = ISO8583Message.fromBuffer(msgData);
        this.messageRouter.route(isoMessage, session).then((response) => {
          if (response) socket.write(response.toBuffer());
        });
      }
    });
  }
}

Authorization Handler

export class AuthorizationHandler implements MessageHandler {
  public async handle(message: ISO8583Message, session: Session): Promise<ISO8583Message> {
    const pan = message.getDEValue(2);
    const amount = parseInt(message.getDEValue(4), 10);
    const terminalId = message.getDEValue(41);
    const merchantId = message.getDEValue(42);

    const card = await this.cardRepo.findByPAN(pan);
    if (!card) return this.buildResponse(message, '14', 'Invalid card');

    if (card.status !== 'ACTIVE') return this.buildResponse(message, '62', 'Restricted');

    if (message.hasDE(52)) {
      const pinValid = await this.hsm.verifyPIN(message.getDEValue(52), card.pan, card.pinBlock);
      if (!pinValid) return this.buildResponse(message, '55', 'Incorrect PIN');
    }

    const fraudCheck = await this.fraudService.check({ pan, amount, merchantId, terminalId });
    if (fraudCheck.isHighRisk) return this.buildResponse(message, '05', 'Do not honor');

    const balance = await this.cardRepo.getAvailableBalance(card.id);
    if (balance < amount) return this.buildResponse(message, '51', 'Insufficient funds');

    const authCode = this.generateAuthCode();
    const rrn = this.generateRRN();

    await this.cardRepo.reserveFunds(card.id, amount, rrn);

    const response = this.buildResponse(message, '00', 'Approved');
    response.setDE(37, rrn, DataElementType.FIXED);
    response.setDE(38, authCode, DataElementType.FIXED);

    return response;
  }

  private generateRRN(): string {
    const now = new Date();
    const julianDay = this.getJulianDay(now).toString().padStart(3, '0');
    const seq = Math.floor(Math.random() * 1000000).toString().padStart(6, '0');
    return julianDay + now.getHours().toString().padStart(2, '0') + seq;
  }
}

Fluxo Completo: Transação de Cartão

Response Codes Mais Comuns

Código	Significado
00	Approved
05	Do not honor
14	Invalid card number
30	Format error
51	Insufficient funds
54	Expired card
55	Incorrect PIN
62	Restricted card
91	Issuer unavailable
96	System malfunction

Comparação: TypeScript vs Go

Aspecto	TypeScript	Go
Parse binário	Buffer API (ok)	encoding/binary (nativo)
TCP Server	net module (bom)	net package (otimizado)
Bitmap	BigInt (funcional)	uint64 (zero overhead)
Memória/conexão	~5MB	~0.5MB
Latência parse	5-20ms	0.5-2ms
Throughput	~5K msg/s	~50K msg/s
Crypto	node crypto (ok)	stdlib (AES-NI hardware)

Casos Reais no Brasil

• Stone (Go) — 5M+ maquininhas, P99 < 3ms, 50K TPS
• Cielo (Java + Go) — 6M+ estabelecimentos, multi-network
• Rede/Itaú (Java) — Stack enterprise, HSM Thales
• PagSeguro (Híbrido) — 30M+ clientes, TypeScript + Java + Go

Boas Práticas

Faça:

• Connection pooling e heartbeats
• Idempotência com STAN + RRN
• Audit trail de todas as mensagens
• Circuit breakers para emissores
• PCI-DSS compliance

Evite:

• Logar PANs (viola PCI-DSS)
• Logar PINs (jamais)
• Chaves em código (use HSM)
• Timeouts longos
• Conexões sem heartbeat

Arquitetura ISO 8583 em Go

Core — Estrutura da Mensagem

package iso8583

import (
    "bytes"
    "encoding/binary"
    "errors"
    "fmt"
    "sync"
)

type Message struct {
    MTI             string
    PrimaryBitmap   uint64
    SecondaryBitmap uint64
    DataElements    map[int][]byte
    mu              sync.RWMutex
}

func NewMessage(mti string) *Message {
    return &Message{MTI: mti, DataElements: make(map[int][]byte)}
}

func (m *Message) SetDE(de int, value []byte) error {
    if de < 2 || de > 128 {
        return fmt.Errorf("DE-%d fora do range", de)
    }
    m.mu.Lock()
    defer m.mu.Unlock()
    if de > 64 { m.setBit(1) }
    m.setBit(de)
    m.DataElements[de] = value
    return nil
}

func (m *Message) GetDE(de int) ([]byte, bool) {
    m.mu.RLock()
    defer m.mu.RUnlock()
    v, ok := m.DataElements[de]
    return v, ok
}

func (m *Message) HasDE(de int) bool { return m.isBitSet(de) }

func (m *Message) setBit(bit int) {
    if bit <= 64 {
        m.PrimaryBitmap |= (1 << uint64(64-bit))
    } else {
        m.SecondaryBitmap |= (1 << uint64(128-bit))
    }
}

func (m *Message) isBitSet(bit int) bool {
    if bit <= 64 {
        return (m.PrimaryBitmap & (1 << uint64(64-bit))) != 0
    }
    return (m.SecondaryBitmap & (1 << uint64(128-bit))) != 0
}

func (m *Message) Marshal() ([]byte, error) {
    var buf bytes.Buffer
    buf.WriteString(m.MTI)
    binary.Write(&buf, binary.BigEndian, m.PrimaryBitmap)
    if m.isBitSet(1) {
        binary.Write(&buf, binary.BigEndian, m.SecondaryBitmap)
    }
    des := make([]int, 0, len(m.DataElements))
    for de := range m.DataElements {
        if m.isBitSet(de) { des = append(des, de) }
    }
    sort.Ints(des)
    for _, de := range des {
        data, _ := m.marshalDE(de, m.DataElements[de])
        buf.Write(data)
    }
    return buf.Bytes(), nil
}

func Unmarshal(data []byte) (*Message, error) {
    if len(data) < 12 { return nil, errors.New("dados insuficientes") }
    msg := &Message{DataElements: make(map[int][]byte)}
    offset := 0
    msg.MTI = string(data[offset : offset+4])
    offset += 4
    msg.PrimaryBitmap = binary.BigEndian.Uint64(data[offset : offset+8])
    offset += 8
    if msg.isBitSet(1) {
        msg.SecondaryBitmap = binary.BigEndian.Uint64(data[offset : offset+8])
        offset += 8
    }
    for de := 2; de <= 128; de++ {
        if !msg.isBitSet(de) { continue }
        value, bytesRead, err := msg.unmarshalDE(de, data[offset:])
        if err != nil { return nil, err }
        msg.DataElements[de] = value
        offset += bytesRead
    }
    return msg, nil
}

func (m *Message) CreateResponse(responseMTI string) *Message {
    response := NewMessage(responseMTI)
    fieldsToCopy := []int{2, 3, 4, 7, 11, 14, 22, 35, 41, 42}
    for _, de := range fieldsToCopy {
        if v, ok := m.DataElements[de]; ok {
            response.SetDE(de, v)
        }
    }
    return response
}

TCP Server — Alta Performance

package server

import (
    "context"
    "encoding/binary"
    "fmt"
    "io"
    "net"
    "sync"
    "sync/atomic"
    "time"
    "go.uber.org/zap"
)

type TCPServer struct {
    config       Config
    router       *router.MessageRouter
    logger       *zap.Logger
    listener     net.Listener
    connections  sync.Map
    connCount    int64
    msgProcessed int64
    shutdown     chan struct{}
    wg           sync.WaitGroup
}

func (s *TCPServer) Start(ctx context.Context) error {
    addr := fmt.Sprintf("%s:%d", s.config.Host, s.config.Port)
    listener, err := net.Listen("tcp", addr)
    if err != nil { return err }
    s.listener = listener
    s.wg.Add(1)
    go s.acceptLoop(ctx)
    return nil
}

func (s *TCPServer) acceptLoop(ctx context.Context) {
    defer s.wg.Done()
    for {
        select {
        case <-ctx.Done(): return
        case <-s.shutdown: return
        default:
            conn, err := s.listener.Accept()
            if err != nil { continue }
            if atomic.LoadInt64(&s.connCount) >= int64(s.config.MaxConnections) {
                conn.Close()
                continue
            }
            s.wg.Add(1)
            go s.handleConnection(ctx, conn)
        }
    }
}

func (s *TCPServer) handleConnection(ctx context.Context, conn net.Conn) {
    defer s.wg.Done()
    defer conn.Close()
    atomic.AddInt64(&s.connCount, 1)
    defer atomic.AddInt64(&s.connCount, -1)

    conn.SetKeepAlive(true)
    buffer := make([]byte, 65536)
    var messageBuffer []byte

    for {
        select {
        case <-ctx.Done(): return
        case <-s.shutdown: return
        default:
            conn.SetReadDeadline(time.Now().Add(s.config.IdleTimeout))
            n, err := conn.Read(buffer)
            if err != nil { return }

            messageBuffer = append(messageBuffer, buffer[:n]...)
            for {
                if len(messageBuffer) < 2 { break }
                msgLen := int(binary.BigEndian.Uint16(messageBuffer[:2]))
                if len(messageBuffer) < 2+msgLen { break }

                msgData := messageBuffer[2 : 2+msgLen]
                messageBuffer = messageBuffer[2+msgLen:]

                msg, err := iso8583.Unmarshal(msgData)
                if err != nil { continue }

                response, err := s.router.Route(ctx, msg)
                if err != nil || response == nil { continue }

                respData, _ := response.Marshal()
                lenHeader := make([]byte, 2)
                binary.BigEndian.PutUint16(lenHeader, uint16(len(respData)))
                conn.Write(lenHeader)
                conn.Write(respData)
                atomic.AddInt64(&s.msgProcessed, 1)
            }
        }
    }
}

func (s *TCPServer) Stop() error {
    close(s.shutdown)
    s.listener.Close()
    s.connections.Range(func(k, v interface{}) bool {
        v.(net.Conn).Close()
        return true
    })
    s.wg.Wait()
    return nil
}

Authorization Handler

package handlers

import (
    "context"
    "fmt"
    "math/rand"
    "strconv"
    "time"
    "go.uber.org/zap"
)

type AuthorizationHandler struct {
    cardService  *services.CardService
    limitService *services.LimitService
    fraudService *services.FraudService
    hsmService   *services.HSMService
    logger       *zap.Logger
}

func (h *AuthorizationHandler) Handle(ctx context.Context, msg *iso8583.Message) (*iso8583.Message, error) {
    pan, _ := msg.GetDEString(2)
    amountStr, _ := msg.GetDEString(4)
    stan, _ := msg.GetDEString(11)
    terminalID, _ := msg.GetDEString(41)
    merchantID, _ := msg.GetDEString(42)

    amount, err := strconv.ParseInt(amountStr, 10, 64)
    if err != nil { return h.buildResponse(msg, "30"), nil }

    card, err := h.cardService.FindByPAN(ctx, pan)
    if err != nil { return h.buildResponse(msg, "96"), nil }
    if card == nil { return h.buildResponse(msg, "14"), nil }

    if card.Status != "ACTIVE" { return h.buildResponse(msg, "62"), nil }

    expDate, _ := msg.GetDEString(14)
    if !h.validateExpiration(card.ExpDate, expDate) {
        return h.buildResponse(msg, "54"), nil
    }

    if msg.HasDE(52) {
        pinData, _ := msg.GetDE(52)
        valid, _ := h.hsmService.VerifyPIN(ctx, pinData, card.PAN, card.PINBlock)
        if !valid { return h.buildResponse(msg, "55"), nil }
    }

    fraudCtx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
    defer cancel()
    fraudResult, _ := h.fraudService.Check(fraudCtx, fraudCheckInput{
        PAN: pan, Amount: amount, MerchantID: merchantID,
    })
    if fraudResult != nil && fraudResult.IsHighRisk {
        return h.buildResponse(msg, "05"), nil
    }

    balance, _ := h.cardService.GetAvailableBalance(ctx, card.ID)
    if balance < amount { return h.buildResponse(msg, "51"), nil }

    authCode := h.generateAuthCode()
    rrn := h.generateRRN()
    h.cardService.ReserveFunds(ctx, card.ID, amount, rrn)

    response := h.buildResponse(msg, "00")
    response.SetDE(37, []byte(rrn))
    response.SetDE(38, []byte(authCode))
    return response, nil
}

func (h *AuthorizationHandler) generateRRN() string {
    now := time.Now()
    return fmt.Sprintf("%03d%02d%06d", now.YearDay(), now.Hour(), rand.Intn(1000000))
}

HSM Service — Integração com Hardware

package services

import (
    "crypto/des"
    "errors"
    "go.uber.org/zap"
)

type HSMService struct {
    logger *zap.Logger
    keys   map[string][]byte
}

func (h *HSMService) VerifyPIN(ctx context.Context, pinBlock, pan, storedPINBlock []byte) (bool, error) {
    if len(pinBlock) != 8 || len(storedPINBlock) != 8 {
        return false, errors.New("PIN block deve ter 8 bytes")
    }
    pinKey := h.loadKeyFromHSM("pin_key")
    decrypted, _ := h.decrypt3DES(pinBlock, pinKey)
    storedDecrypted, _ := h.decrypt3DES(storedPINBlock, pinKey)
    return h.comparePINBlocks(decrypted, storedDecrypted), nil
}

func (h *HSMService) CalculateMAC(ctx context.Context, data, key []byte) ([]byte, error) {
    block, _ := aes.NewCipher(key[:16])
    iv := make([]byte, block.BlockSize())
    mode := cipher.NewCBCEncrypter(block, iv)
    paddingSize := block.BlockSize() - (len(data) % block.BlockSize())
    padded := make([]byte, len(data)+paddingSize)
    copy(padded, data)
    for i := len(data); i < len(padded); i++ { padded[i] = byte(paddingSize) }
    encrypted := make([]byte, len(padded))
    mode.CryptBlocks(encrypted, padded)
    mac := make([]byte, 8)
    copy(mac, encrypted[len(encrypted)-8:])
    return mac, nil
}

func (h *HSMService) encrypt3DES(data, key []byte) ([]byte, error) {
    block, _ := des.NewTripleDESCipher(key)
    result := make([]byte, len(data))
    block.Encrypt(result, data)
    return result, nil
}

Otimizações de Performance em Go

Otimização	Impacto
Zero-copy parsing	Buffer slicing, sem cópia
sync.Pool	Reutilização de buffers
sync.Map	Lock-free para conexões
Atomic counters	Métricas sem locks
encoding/binary	Parsing nativo otimizado
Keepalive	Detecção rápida de falhas
AES-NI	Hardware acceleration para crypto

Benchmark: Go vs TypeScript

Operação	TS P99	Go P99	TS Throughput	Go Throughput
Parse	8ms	1ms	25K/s	75K/s
Authorization	18ms	3ms	8K/s	45K/s
HSM Crypto	12ms	2ms	5K/s	32K/s
Full Pipeline	28ms	8ms	3K/s	22K/s

Casos de Uso no Brasil

• Stone (Go) — 5M+ maquininhas, 50K+ TPS, P99 < 3ms
• Cielo (Java + Go) — 6M+ estabelecimentos, IBM Mainframe legacy
• PagSeguro (Híbrido) — 30M+ clientes, Go + Java + TypeScript
• Bandeiras (Java + Go) — Bilhões/dia, multi-region

Arquitetura Híbrida Recomendada

Regra de ouro: Use Go para o caminho do dinheiro (ISO 8583, authorization, HSM) e TypeScript para o caminho do cliente (BFFs, APIs REST).

Decisão Final

Cenário	Escolha
Adquirente grande / Bandeira	Go
10K+ TPS sustentado	Go
SLA P99 < 5ms	Go
MVP / Prototipagem	TypeScript
Sub-adquirente pequeno	TypeScript
Gateway REST	TypeScript

---

Como testar

# TypeScript
cd packages/backend/iso8583
pnpm dev

# Go
cd packages/backend/iso8583-go
go run .

# Enviar mensagem de teste
echo -n "0100..." | nc localhost 3004

---

Lições aprendidas

1. Bitmaps são o coração — Sem entender bitmaps, não se entende ISO 8583
2. Binário é preciso — Um byte errado = mensagem rejeitada
3. Response codes importam — 00=OK, 51=Sem fundos, 55=PIN errado
4. RRN é crucial — Referência única para reconciliação
5. PCI-DSS não é opcional — Nunca logar PANs ou PINs
6. HSM é obrigatório — Criptografia de PINs em hardware
7. Go é a escolha natural — 4-8x mais rápido que Node.js
8. Heartbeats salvam vidas — Conexões TCP precisam de 0800 periódico
9. Circuit breakers — Emissores caem, prepare-se
10. O protocolo tem 35+ anos — E continua sendo essencial