Module 1: ISO8583 Foundations & Message Anatomy

Why Does ISO8583 Exist?

Picture this: It's 1987. You're an engineer at a regional bank in the United States. Your ATM network works fine—your machines talk to your core banking system using a protocol your team designed. Life is good.

Then corporate decides to join a new interbank network. Now your ATMs need to talk to other banks' systems. Their ATMs need to talk to yours. The regional network wants to connect to a national network. Suddenly, you realize the problem: everyone invented their own message format.

Bank A sends amounts as ASCII strings with decimal points. Bank B uses packed BCD without decimals (they assume 2 decimal places). Bank C sends the currency code in a different position. Nobody agrees on how to represent a card number, what fields to include, or even how to indicate "this is an authorization request."

ISO8583 emerged from this chaos.

The International Organization for Standardization published the first version in 1987 specifically for card-originated financial transactions. The goal was simple: create a common language that any financial institution could speak, regardless of their internal systems.

The Problem ISO8583 Solves

Before we dive into the technical details, understand what ISO8583 actually is: a schema for financial messages. It defines:

1. What kinds of messages exist - authorization requests, reversals, network management
2. What fields can appear in each message - card number, amount, merchant info
3. How to encode each field - length prefixes, data types, padding rules
4. How to indicate which fields are present - the bitmap system

It does not define:

• Transport protocol (you can use TCP, X.25, HTTP, carrier pigeon)
• Session management
• Encryption (though it has fields for encrypted data)
• Business logic ("should this card be approved?")

Think of ISO8583 as the "JSON" of 1987—a serialization format with a schema. But where JSON is human-readable and self-describing, ISO8583 is compact and requires you to know the schema to parse it.

Why Not Just Use JSON/XML/Protobuf?

You might wonder: why do we still use a 1987-era binary format when we have modern alternatives?

Performance and bandwidth. A typical authorization request in ISO8583 is 200-400 bytes. The same data in JSON might be 2KB. When you're processing 10,000 transactions per second, those extra bytes matter—for network costs, latency, and parsing overhead.

Backward compatibility. The global payment infrastructure runs on ISO8583. Visa, Mastercard, national switches, ATM networks—they all speak it. Migrating would require coordinated changes across thousands of organizations. The cost would be astronomical.

Density of critical data. Payment messages are time-sensitive. Every millisecond matters in authorization. ISO8583's compact encoding (BCD-packed numbers, fixed-length fields) minimizes the work required to extract critical fields like amount and card number.

Modern payment APIs (Stripe, Square, Adyen) hide ISO8583 behind REST interfaces. But under the hood, when those APIs connect to card networks, they're building and parsing ISO8583 messages.

Message Framing: What Wraps the ISO8583 Message

Before we look inside an ISO8583 message, you need to understand what wraps it. In production, you'll never receive a raw ISO8583 message—it always comes inside a transport frame.

The Length Header

Almost every implementation prefixes the message with a length indicator:

┌─────────────────┬────────────────────────────────────────────────────┐
│  Length Header  │              ISO8583 Message                       │
│   (2-4 bytes)   │                                                    │
└─────────────────┴────────────────────────────────────────────────────┘

The length header tells you how many bytes follow. Without it, you can't know where one message ends and the next begins on a TCP stream.

Common length header formats:

Critical detail: The length might include or exclude itself. If a message is 200 bytes and uses a 2-byte header:

• Length excludes header: Header contains 00 C8 (200), total transmission is 202 bytes
• Length includes header: Header contains 00 CA (202), total transmission is 202 bytes

You must know which convention your network uses. Getting this wrong means every message parse fails.

TPDU Headers (Transport Protocol Data Unit)

Many networks, especially in Asia, Africa, and Latin America, add a TPDU header between the length and the ISO8583 message:

┌────────────┬──────────────┬────────────────────────────────────────┐
│   Length   │    TPDU      │           ISO8583 Message              │
│  (2 bytes) │  (5 bytes)   │                                        │
└────────────┴──────────────┴────────────────────────────────────────┘

A typical TPDU structure:

TPDU: 60 00 00 00 00
      │  │  │  │  │
      │  └──┴──┴──┴─── Destination/Source addresses (network-specific)
      └─── Protocol ID (0x60 = ISO8583)

The TPDU identifies the message protocol and routing information. If you're integrating with a switch that uses TPDU, you'll need to:

1. Parse and validate the TPDU
2. Strip it before processing the ISO8583 portion
3. Build a proper TPDU for responses

When you see garbage before the MTI, check for length headers and TPDU. This is the #1 cause of "my parser doesn't work" issues.

The Anatomy of an ISO8583 Message

Now let's look inside. Every ISO8583 message has exactly three parts, always in this order:

┌──────────────────────────────────────────────────────────────────────┐
│                         ISO8583 Message                              │
├──────────┬─────────────────────┬─────────────────────────────────────┤
│   MTI    │      Bitmap(s)      │           Data Elements             │
│ 4 bytes  │    8 or 16 bytes    │          variable length            │
│          │   (or 24 for 2003)  │                                     │
└──────────┴─────────────────────┴─────────────────────────────────────┘

Let's examine each part.

Part 1: The Message Type Indicator (MTI)

The MTI is 4 characters that tell you everything about the message's purpose before you parse a single field. It answers four questions:

Position:   0         1         2         3
            │         │         │         │
            ▼         ▼         ▼         ▼
MTI:        0         1         0         0
            │         │         │         │
            │         │         │         └─ Origin: Who sent this?
            │         │         └─ Function: Request or response?
            │         └─ Class: What kind of transaction?
            └─ Version: Which ISO8583 spec?

Position 0: Version

When you see a message starting with 0, you're looking at a 1987-spec message. Most production systems still use this. Messages starting with 2 are 2003-spec—you'll see these in newer implementations and some regional networks.

Position 1: Message Class

This is the most important digit for understanding what's happening:

In daily operations, you'll mostly see classes 1, 4, and 8:

• Class 1 (Authorization): The bread and butter. Every swipe, tap, or online purchase.
• Class 4 (Reversal): When things go wrong. Timeout? Reversal. Customer changed mind? Reversal.
• Class 8 (Network Management): The housekeeping. "Are you there?" (echo), "I'm signing on" (sign-on), "New encryption keys" (key exchange).

Position 2: Function

The request/response pair is fundamental. Every x0 message expects an x1 response:

• 0100 (auth request) → 0110 (auth response)
• 0400 (reversal request) → 0410 (reversal response)
• 0800 (network mgmt request) → 0810 (network mgmt response)

Position 3: Origin

The distinction between 0 and 1 matters for duplicate detection. When you see 0101 instead of 0100, you know the sender didn't get your response and is retrying. Your system needs to handle this—either re-process or return the cached response.

Putting It Together: Reading MTIs

Let's decode some real MTIs:

0100 - The most common message in payments

• 0 = 1987 spec
• 1 = Authorization
• 0 = Request
• 0 = From acquirer (first attempt)

Translation: "This is an authorization request using the 1987 spec, sent by an acquirer for the first time." In other words: someone's trying to use their card.

0110 - The response to 0100

• 0 = 1987 spec
• 1 = Authorization
• 1 = Response
• 0 = From... wait, origin in responses is weird

In responses, the origin digit often mirrors the request or indicates who's responding. Practice varies by network.

0420 - A reversal repeat

• 0 = 1987 spec
• 4 = Reversal
• 2 = Advice (it's informing, not asking)
• 0 = From acquirer

Translation: "I'm telling you (not asking) to reverse a transaction." This happens after a timeout—the acquirer doesn't know if the original went through, so they send an advice to reverse it.

0800 - Network management

• 0 = 1987 spec
• 8 = Network management
• 0 = Request
• 0 = From acquirer

Translation: "This is a network management request." Could be echo test ("are you alive?"), sign-on ("I'm starting my shift"), or key exchange ("let's update encryption keys").

Part 2: The Bitmap

Here's where ISO8583 gets clever. The bitmap is a 64-bit (or 128-bit, or 192-bit) field where each bit indicates whether a specific data element is present.

Bitmap (hexadecimal): 7234 0001 08E1 8000
Bitmap (binary):      0111 0010 0011 0100 0000 0000 0000 0001
                      0000 1000 1110 0001 1000 0000 0000 0000

Bit position:         1234 5678 9... (continuing to 64)

If bit N is set to 1, then Data Element N is present in the message. If it's 0, that field is absent.

Why bits instead of tags?

Consider the alternative: you could prefix each field with an identifier, like <field id="2">4532123456789012</field>. But that's 15+ bytes of overhead per field. In a message with 20 fields, that's 300+ bytes just for metadata.

The bitmap approach: 8 bytes tells you exactly which of 64 possible fields are present. Then you parse fields in order—no per-field identifiers needed.

The Secondary Bitmap Trick

What if you need more than 64 fields? Here's the elegant solution: Bit 1 of the primary bitmap indicates whether a secondary bitmap follows.

Primary bitmap bit 1 = 0: Only fields 1-64 possible
Primary bitmap bit 1 = 1: Secondary bitmap follows, fields 65-128 possible

Important clarification: Field 1 (DE1) is the secondary bitmap. It's not a separate data element with its own content—when bit 1 is set, the "data" for Field 1 is the 8-byte secondary bitmap itself.

Bit 1 = 0:
┌─────────────────────────┬────────────────────────────┐
│  Primary Bitmap (8 bytes)│     Data Elements          │
│  Bit 1 = 0              │     (DE2, DE3, ...)        │
└─────────────────────────┴────────────────────────────┘

Bit 1 = 1:
┌─────────────────────────┬─────────────────────────┬────────────────────┐
│  Primary Bitmap (8 bytes)│ Secondary Bitmap (8 bytes)│   Data Elements    │
│  Bit 1 = 1              │ (This IS Field 1/DE1)   │   (DE2, DE3, ...)  │
└─────────────────────────┴─────────────────────────┴────────────────────┘

This confuses many beginners who expect to find "Field 1 data" somewhere. There is no Field 1 data—Field 1's presence means "look at the next 8 bytes as a secondary bitmap."

The 2003 spec extends this pattern: bit 65 of the secondary bitmap indicates whether a tertiary bitmap (Field 65) follows, allowing fields 129-192.

In practice:

• Most authorization messages only use the primary bitmap
• Secondary bitmap appears when you need fields like DE64 (MAC) or DE127-128 (private use)
• Tertiary bitmap is rare, used in extended 2003-spec implementations

Part 3: Data Elements

After the bitmap(s), the data elements appear in order of their field numbers, but only for fields where the corresponding bit is set.

If your bitmap indicates fields 2, 3, 4, 11, and 12 are present, the data appears as:

[Field 2 data][Field 3 data][Field 4 data][Field 11 data][Field 12 data]

No separators. No field IDs. You parse field 2, advance your cursor, parse field 3, advance, and so on.

This requires knowing the length of each field. ISO8583 fields come in three flavors:

1. Fixed length: The spec says field X is always N bytes. Parse exactly N bytes.
2. LLVAR: The first 2 characters are the length, then the data. "19" followed by 19 bytes.
3. LLLVAR: The first 3 characters are the length. "099" followed by 99 bytes.

We'll dive deep into encoding in Module 3. For now, understand that you can't parse an ISO8583 message without knowing the field specifications.

Wire Format and Hex Representation

When you capture ISO8583 traffic or look at logs, you'll see messages in hexadecimal. Let's decode a real authorization request:

0100723A448108E180001654123456789012340000000010000000011212345612345678901234567890

Let's break this down byte by byte:

The MTI

30 31 30 30

Wait, that doesn't look like 0100. Here's the trick: 30 is ASCII for '0', 31 is ASCII for '1'. The MTI is transmitted as ASCII characters, so 0100 becomes 30313030 in hex.

Understanding BCD vs ASCII Encoding

This is where many engineers get confused. ISO8583 data can be encoded in different ways, and you must know which your network uses.

ASCII Encoding (most common in modern systems):

• Each character takes 1 byte
• Human-readable in hex dumps
• MTI 0100 → 30 31 30 30 (4 bytes)
• Number 1234 → 31 32 33 34 (4 bytes)

BCD Encoding (Binary Coded Decimal):

• Each digit takes 4 bits (half a byte)
• Two digits pack into one byte
• MTI 0100 → 01 00 (2 bytes)
• Number 1234 → 12 34 (2 bytes)

Side-by-side comparison:

Value:        0  1  0  0

ASCII hex:    30 31 30 30     (4 bytes)
BCD hex:      01 00           (2 bytes)

Value:        1  2  3  4  5  6

ASCII hex:    31 32 33 34 35 36    (6 bytes)
BCD hex:      12 34 56             (3 bytes)

How to tell which you're dealing with:

• If you see 30, 31, 32... 39 patterns → ASCII (these are ASCII codes for '0'-'9')
• If you see values like 01, 12, 99 that match the visible digits → BCD
• Check your network specification document (it will say)

The bitmap can also vary:

Bitmap indicating fields 2,3,4 present:

Binary (raw bytes):     72 00 00 00 00 00 00 00   (8 bytes)
Hex-ASCII string:       "7200000000000000"        (16 characters = 16 bytes)

Some networks transmit the bitmap as a hex-encoded ASCII string (doubling the size). When you see a 16-character bitmap where you expected 8 bytes, this is why.

Production tip: When your parser fails, the first thing to check is encoding mismatch. Print the raw bytes and look for the telltale 30-39 range that indicates ASCII encoding.

The Bitmap

72 3A 44 81 08 E1 80 00

This is 8 bytes = 64 bits. Let's convert to binary:

72 = 0111 0010
3A = 0011 1010
44 = 0100 0100
81 = 1000 0001
08 = 0000 1000
E1 = 1110 0001
80 = 1000 0000
00 = 0000 0000

Reading left to right, bit 1 is the leftmost bit of the first byte:

• Bit 1 = 0 → No secondary bitmap
• Bit 2 = 1 → Field 2 (PAN) present
• Bit 3 = 1 → Field 3 (Processing code) present
• Bit 4 = 1 → Field 4 (Amount) present
• Bit 5 = 0 → Field 5 absent
• ...and so on

Fields present in this message: 2, 3, 4, 7, 11, 12, 14, 22, 23, 25, 26, 32, 35, 41, 42, 49, 52.

The Data Elements

After the bitmap, we have the actual data. Knowing which fields are present, we parse them in order. Let's decode more fields from our example:

Field 2 (PAN) - Primary Account Number, LLVAR format:

31 36 35 34 31 32 33 34 35 36 37 38 39 30 31 32 33 34
│  │  └────────────────────────────────────────────┘
│  │               16 digits of PAN
└──┴─ Length prefix "16" (ASCII)

Decoded: Length=16, PAN=5412345678901234

Field 3 (Processing Code) - Fixed 6 digits:

30 30 30 30 30 30
└──────────────┘
   "000000"

Decoded: 000000

The processing code has internal structure (often overlooked):

Processing Code: XX YY ZZ
                 │  │  │
                 │  │  └─ To Account Type
                 │  └──── From Account Type
                 └─────── Transaction Type

Common transaction types (first 2 digits):
  00 = Purchase / Goods and services
  01 = Cash withdrawal
  09 = Purchase with cashback
  20 = Return / Refund
  30 = Balance inquiry
  31 = Balance inquiry (savings)

Account types (digits 3-4 and 5-6):
  00 = Default / Unspecified
  10 = Savings account
  20 = Checking account
  30 = Credit account

Example: "011020" = Cash withdrawal from savings to checking
Example: "200000" = Refund to default account

Field 4 (Amount, Transaction) - Fixed 12 digits:

30 30 30 30 30 30 30 31 30 30 30 30
└──────────────────────────────────┘
         "000000010000"

Decoded: 000000010000 = 100.00 (amount in minor currency units)

Amounts are in the smallest currency unit (cents for USD, pence for GBP). No decimal point is transmitted—the currency's exponent (from DE49) tells you where to place it.

Field 7 (Transmission Date/Time) - Fixed 10 digits (MMDDhhmmss):

31 32 32 39 31 34 33 30 35 32
└──────────────────────────────┘
        "1229143052"

Decoded: 12/29 14:30:52 (December 29th, 2:30:52 PM)

Field 11 (STAN - System Trace Audit Number) - Fixed 6 digits:

31 32 33 34 35 36
└────────────────┘
    "123456"

Decoded: 123456 (unique per terminal per day)

Field 12 (Local Transaction Time) - Fixed 6 digits (hhmmss):

31 32 33 34 35 36
└────────────────┘
    "123456"

Decoded: 12:34:56 (local time at terminal)

This walkthrough shows the pattern: once you know the bitmap, you parse fields in order using the field specification (fixed length vs LLVAR vs LLLVAR) from the spec.

1987 vs 2003: Key Differences

While both versions share the same fundamental structure, the 2003 spec introduced several changes:

Field Definition Changes

Encoding Flexibility

The 2003 spec is more explicit about encoding options and provides clearer guidance on:

• Character sets (UTF-8 support)
• Variable length field maximum sizes
• Sub-element structures within fields

MTI Differences

The version digit matters:

• 0xxx = 1987 format, 1987 field definitions
• 2xxx = 2003 format, 2003 field definitions

A parser must check the version to know which field specifications to apply.

Practical Impact

In practice, most of the world still runs on 1987-spec messages. You'll encounter 2003-spec in:

• Newer regional networks
• Some domestic switches
• Modern implementations that started after ~2010

The core concepts (MTI, bitmap, ordered fields) are identical. The differences are in field definitions and edge cases.

How Messages Flow: Authorization

Let's trace a real authorization flow to see ISO8583 in action.

The Scenario

Alice uses her Visa card at a coffee shop in Seattle. The shop's terminal is connected to Chase (the acquirer). Alice's card was issued by Bank of America (the issuer).

Step 1: Terminal → Acquirer

The terminal builds an ISO8583 message:

MTI: 0100 (auth request)
DE2:  Card number
DE3:  000000 (purchase)
DE4:  000000000350 ($3.50)
DE7:  1229143052 (timestamp)
DE11: 123456 (STAN - System Trace Audit Number)
DE22: 051 (entry mode: chip)
DE35: Track 2 data (encrypted)
DE41: TERMINAL1 (terminal ID)
DE42: MERCHANT00001234 (merchant ID)
DE49: 840 (USD)
DE52: PIN block (encrypted)
DE55: EMV chip data

The terminal sends this over TCP to Chase's payment gateway.

Step 2: Acquirer → Network

Chase receives the message, validates the format, adds acquirer-specific fields (DE32: Acquiring Institution ID), and routes to Visa based on the card's BIN (Bank Identification Number).

MTI: 0100
DE2:  Card number
DE3:  000000
DE4:  000000000350
...
DE32: 123456 (Chase's institution ID) ← Added by acquirer
DE33: 456789 (Forwarding institution) ← Sometimes added

Step 3: Network → Issuer

Visa receives the message, performs network-level validation, and routes to Bank of America based on the card number.

The message may be transformed slightly—Visa might add their own fields (DE63 with Visa-specific data) or modify formats.

Step 4: Issuer Decision

Bank of America's authorization system:

1. Decrypts the PIN block
2. Validates the PIN
3. Checks available balance
4. Applies fraud rules
5. Makes approve/decline decision

Step 5: Response Flow (Reverse Path)

Bank of America builds the response:

MTI: 0110 (auth response)
DE2:  Card number (echoed)
DE3:  000000 (echoed)
DE4:  000000000350 (echoed)
...
DE11: 123456 (echoed - critical for matching)
DE38: ABC123 (authorization code)
DE39: 00 (approved)

Field 39 (Response Code) is the answer everyone's waiting for:

• 00 = Approved
• 05 = Do not honor
• 14 = Invalid card number
• 51 = Insufficient funds
• 54 = Expired card

The response travels back: Issuer → Visa → Chase → Terminal → Receipt printed.

The Matching Problem

When Chase gets the response, how does it know which request it matches?

Message matching fields:

• DE11 (STAN): System Trace Audit Number - unique per terminal per day
• DE12/13: Local transaction time/date
• DE32: Acquiring institution ID
• DE37: Retrieval Reference Number

The combination of STAN + timestamp + acquirer ID uniquely identifies the original request. The response must echo these fields so the acquirer can correlate.

Timing Matters

Authorization must be fast. Typical SLAs:

• Terminal → Acquirer: < 1 second
• Full round trip: < 3 seconds

If the acquirer doesn't get a response within ~30 seconds, they have a problem: did the authorization go through or not? This triggers the reversal flow (MTI 0400), which we'll cover in Module 5.

Common Pitfalls

After years of ISO8583 work, certain mistakes appear repeatedly. Learn from others' pain:

1. Off-by-One in Bitmap Parsing

The bitmap uses 1-based indexing, but arrays use 0-based indexing:

Bitmap byte 0:  0111 0010
                ││││ ││││
Bit numbers:    1234 5678   ← ISO8583 numbering (1-based)
Array indices:  0123 4567   ← Programming (0-based)

The fix: When checking if field N is present, look at bit index N-1:

// WRONG: fieldPresent = (bitmap[fieldNum/8] >> (7 - fieldNum%8)) & 1
// RIGHT: fieldPresent = (bitmap[(fieldNum-1)/8] >> (7 - (fieldNum-1)%8)) & 1

2. Bitmap Endianness

ISO8583 bitmaps are big-endian (network byte order). Bit 1 is the leftmost bit of the first byte:

Hex:    72          3A          ...
Binary: 0111 0010   0011 1010   ...
Bits:   1234 5678   9...        ...

Many bugs come from reading bits right-to-left or reversing byte order.

3. Confusing Hex Representation vs Raw Bytes

When you see 723A448108E18000 in a log:

• It might be 8 raw bytes: 72 3A 44 81 08 E1 80 00
• It might be 16 ASCII characters: 37 32 33 41 34 34 38 31 30 38 45 31 38 30 30 30

How to tell: Check the byte count. If parsing fails and you're getting weird results, try treating the bitmap as hex-encoded ASCII.

4. Length Header Confusion

The two most common length header bugs:

1. Forgetting the length header exists - Your MTI looks like garbage because you're parsing length bytes as the MTI
2. Wrong inclusion - Length says 200, but that includes/excludes the 2-byte header itself

Debug tip: Print the first 10 bytes in hex. If bytes 0-1 look like a reasonable length and bytes 2-5 look like an MTI (e.g., 30 31 30 30), you have a 2-byte length header.

5. STAN Uniqueness Scope

The STAN (DE11) must be unique per terminal per day. Common mistakes:

• Using a global counter (conflicts between terminals)
• Not resetting at midnight (duplicate STANs next day)
• Using random numbers (potential collisions)

The pattern: STAN = (terminal_sequence++) % 1000000, reset at midnight local time.

6. Amount Field Decimal Handling

Amounts are in minor currency units with NO decimal point:

• 000000010000 with USD (exponent 2) = $100.00
• 000000010000 with JPY (exponent 0) = ¥10000
• 000000010000 with KWD (exponent 3) = 10.000 KWD

The bug: Assuming all currencies have 2 decimal places. Always check DE49 (currency code) and use the ISO 4217 exponent.

7. Response Code Assumptions

Not all response codes mean what you think:

• 00 = Approved ✓
• 05 = "Do not honor" - Could be fraud, could be issuer system error
• 51 = "Insufficient funds" - Don't show this to customers (privacy)
• 91 = "Issuer unavailable" - Retry might work

Best practice: Map network response codes to your own codes. Never expose raw ISO8583 response codes to end users.

8. Timeout and Reversal Race Conditions

Timeline:
0s    - Send 0100 authorization
30s   - No response, send 0400 reversal
31s   - Original 0110 response arrives (was just slow)
32s   - 0410 reversal response arrives

Now what? The auth was approved, then reversed.

The fix: Once you send a reversal, ignore any late-arriving authorization response. The reversal takes precedence.

The Parse Contract: A Layered, Deterministic Model

Every parser should treat ISO8583 as a sequence of strict contracts, not a best-effort transform.

Layer 0: Framing Contract (Stream-safe)

Before MTI parsing, determine transport envelope:

1. Consume length header (if configured, or auto-detect by gateway mode).
2. Confirm the declared length is sufficient for at least a full MTI.
3. Strip optional TPDU if required.
4. Confirm MTI encoding width (4 ASCII bytes or 2 BCD bytes).

If any check fails, fail fast and return a precise error with cursor location.

Why this matters:

• TCP gives a continuous stream, not message boundaries.
• Fragmented or concatenated frames are common in test harnesses and gateways.
• Wrong boundary assumptions cause every field after MTI/bitmap to be shifted.

Frame parse = [Length?] [TPDU?] [MTI] [Bitmap(s)] [Payload]

Layer 1: Control-Bit Contract

1. Parse MTI to resolve version (0, 1, 2).
2. Parse primary bitmap.
3. If primary bit 1 = 1, parse secondary bitmap.
4. If secondary bit 1 = 1 and 2003 mode is enabled, parse tertiary bitmap.
5. Validate each requested bitmap segment before consuming any payload bytes.

Layer 2: Field Contract

For each present field:

• Use the field definition table for this MTI and spec family.
• Apply declared type and prefixing rule (fixed, LLVAR, LLLVAR).
• Enforce max length before slicing bytes.
• Validate and advance cursor only on success.

This prevents “cursor drift” from propagating through the rest of the message.

Layer 3: Business Contract

After decoding fields:

• Validate mandatory combinations (example: DE11+DE12+DE13 for auth matching).
• Validate semantic compatibility (amount/currency exponent, code lists, allowed value spaces).
• Validate response correlation keys for request/response pairs.

If parsing is successful but the business contract fails, log it as semantic rejection.

Progressive Parse Tests (Think in Increasing Difficulty)

Use these as a disciplined implementation path:

Test 1: Framing and MTI

• Input: 00 C8 30 31 30 30 ...
• Expected: length = 200, MTI = 0100, parser enters payload stage.

Test 2: Bitmap Gate

• Input: 30313030 7200000000000000 (ASCII)
• Expected: bitmap=8 bytes, primary bit1=0, no secondary parse.

Test 3: Bitmap Chain Expansion

• Primary bit1=1 but no secondary bytes present.
• Expected: hard failure at bitmap stage before reading fields.

Test 4: Cursor Alignment

• Given known bitmap and field sequence, assert cursor after each field:
  • After DE2 length-prefix bytes
  • After DE2 value bytes
  • After DE3 fixed length
  • ...
• Any mismatch is ERR_ALIGNMENT.

Test 5: Encoding Mismatch

• MTI rendered as ASCII but parser configured BCD-first.
• Expected: early mismatch (ERR_ENCODING_MISMATCH) not silent fallback after first field.

Deeper Behavior: Duplicate, Retry, and Reversal Safety

Production payment traffic is eventually consistent under failure and retries.

Idempotency Key Strategy

For request classes (0100, 0200, 0200 variants):

• Build a deterministic idempotency key from:
  • MTI
  • DE11 (STAN)
  • DE12/DE13 (time/date)
  • DE32 or DE42 (acquirer and/or merchant identifier)

On 0101 retries:

• If request key already in flight, return or reuse pending result.
• If request key already completed, return cached response signature.
• If key unknown, process as a fresh request with explicit duplicate policy.

This avoids hidden double-auth incidents and reduces reconciliation issues in reversal-heavy flows.

Reversal Interaction and Late Responses

• Late 0110 after a 0400/0420 is possible.
• Prefer deterministic state machine:
  • pending → timed out → reversal sent → reversal complete lock
  • late auth response updates to “informational only”

Error Taxonomy and Cursor Integrity

Build parsers with machine-readable failure modes:

• ERR_LENGTH_HEADER (framing issue)
• ERR_BITMAP_TOO_SHORT (control-bit violation)
• ERR_INVALID_LENGTH_PREFIX (field-length contract violation)
• ERR_CURSOR_OUT_OF_BOUNDS (alignment violation)
• ERR_IDEMPOTENCY_MISS (no matching request for response)
• ERR_BITMAP_ENCODING (ASCII/hex vs binary ambiguity)

Each error should include:

• absolute cursor offset
• total bytes available
• expected bytes
• current phase (framing/bitmap/field/correlation)

This turns support noise into actionable incidents.

Summary

ISO8583 is a compact binary format for financial messages that has been the backbone of global payments since 1987. Every message has three parts:

1. MTI (4 bytes): Version, class, function, origin—tells you what kind of message this is
2. Bitmap (8-24 bytes): Bit field indicating which data elements are present
3. Data Elements (variable): The actual payload, parsed in field-number order

Key mental model:

• The MTI answers "what is this?"
• The bitmap answers "what fields are included?"
• The data elements are "the actual content"

When debugging at 3 AM, start with the MTI. 0100? Authorization request. 0110? Authorization response. 0400? Someone's reversing. 0800? Network management. The MTI immediately tells you what you're looking at.

What's Next

In Module 2, we'll dive deep into bitmaps—how to efficiently parse them, build them, and handle the secondary/tertiary bitmap cases. You'll implement a bitmap parser that can decode any ISO8583 bitmap into a list of present field numbers.

But first, let's solidify your MTI understanding with two problems:

1. mti-parser: Parse an MTI string and extract its components
2. message-class-identifier: Given an MTI, classify the transaction type

These are foundational—you'll use MTI parsing in every ISO8583 project you build.