ISO 8583 Bitmap Decoder

What the bitmap does

ISO 8583 messages have no field delimiters. Instead, a bitmap at the front declares which data elements are present, and the receiver reads them in numerical order using the format definitions it already holds. Eight bytes, sixty-four bits, one per data element.

Bit 1, the most significant bit of the first byte, is special. It is not DE 1; it signals that a secondary bitmap follows, covering DE 65 to 128. Within that secondary bitmap, DE 65 in turn signals a tertiary bitmap for DE 129 to 192, though you will rarely meet one in the wild.

A practical consequence: if the first hex digit of your bitmap is 8 or higher, there is a secondary bitmap and the message data starts 16 bytes in, not 8. Getting this wrong shifts every subsequent field and produces the classic "everything parses as garbage" symptom.

Decoding a bitmap by hand

Take 7238048128C08000, a routine authorisation request. The first hex digit is 7, below 8, so bit 1 is clear and there is no secondary bitmap: eight bytes, and the message data starts straight after them.

Then read each byte high bit first. 72 is 0111 0010, giving DE 2, 3, 4 and 7 — PAN, processing code, amount and transmission date. 38 gives DE 11, 12 and 13, the STAN and the local time and date. 04 gives DE 22, the point of service entry mode. 81 gives DE 25 and 32, 28 gives DE 35 and 37, C0 gives DE 41 and 42, the terminal and merchant identifiers, and 80 gives DE 49, the currency. Fifteen fields.

That is the whole algorithm, and it is worth doing once by hand so the failure modes are recognisable afterwards. Reading the bytes low bit first yields a plausible-looking but wrong field set, which is the single most common way this goes quietly wrong.

Finding the bitmap in a raw message

In an ASCII-encoded message the layout is normally a length header, then four characters of MTI, then the bitmap. The bitmap itself may be 16 hex characters (ASCII-encoded, one character per nibble) or 8 raw bytes (binary) depending on the endpoint. Both are common; only the endpoint's specification tells you which.

If a bitmap decode gives you an implausible field set, say DE 3 and DE 4 missing from an authorisation, you are probably off by the length header, or reading ASCII as binary.

Building a bitmap from a field list

The reverse direction is the same rules run backwards, and it is what you want when constructing a test message rather than reading a captured one. Name the data elements you intend to send and the bitmap follows from them; this tool does both directions for that reason.

The one thing worth watching is the moment a field crosses 64. Asking for DE 2, 3, 4, 55 and 70 produces F0000000000002000400000000000000: sixteen bytes rather than eight, because DE 70 lives in the secondary bitmap, and a leading F because bit 1 is now set to announce it. Adding one high-numbered field doubles the bitmap and shifts the start of your data by eight bytes.

Why the rest of the message is harder

The bitmap is the one part of ISO 8583 that works the same everywhere. Field contents are another matter: DE 48, 60-63 and 120-127 are reserved for private use and every processor defines them differently, often as nested TLV or positional substructures. That is why this tool decodes the bitmap and the field names rather than pretending to parse a whole message. Doing that properly needs your acquirer's specification, not a generic parser.

One field is worth pulling out separately: DE 55 is EMV chip data in BER-TLV form. Paste it into the TLV parser.