Decoding an ISO 8583 Payload
Goal: Understand the fixed‑position pieces that make up the ASCII string we receive in
ISOFullMessage, so you can split it by eye or with any language / tool.
1. High‑level Structure
┌──────────────────────────────────────────────────────────────┐
│ Transport / Host header (variable, host‑specific) │
│ ──────────────────────────────────────────────────────────── │
│ MTI 4 n │
│ Primary bitmap 16 n (64 bits → 16 hex characters) │
│ Secondary bitmap 16 n (present only if bit 1 = 1) │
│ Data elements … (1‑128, in ascending order) │
└──────────────────────────────────────────────────────────────┘All characters are ASCII.
Numeric fields (
n) are right‑justified, zero‑padded.Alphanumeric fields (
ans) are left‑justified, space‑padded.Variable‑length fields begin with a numeric length prefix:
LLVAR→ 2 digits (00‑99)LLLVAR→ 3 digits (000‑999)
2. Example in the Wild
Below is the authorization message you saw (line‑wrapped & spaced):
ISO0260000700 | 0120 | B23AC4112EE1801C
0000000214000100 | 0000000000000000 | 0285
0724181349 | 863303 | 141300 | 0724 | 0724
554105 | 2C0000000006 | 12345621543464******6993=0000427704382626
185503 | 0000010003 | 127298000000000
EXXON UPPY'S #68 #2009CENTREVILLE VA US
0100724141353840 | 0160000000
… (continues)What those chunks are
ISO0260000700
Transport header – prepended by the host to carry length, protocol version, routing info. Its size (12–20 bytes) is vendor‑defined.
Not part of ISO 8583 proper. Discard before parsing.
0120
MTI – 0 120 = Authorization Advice.
Always 4 numeric chars.
B23AC4112EE1801C
Primary bitmap (16 hex chars = 64 bits). Bit 1 is set (B = 1011), so a secondary bitmap follows.
Every 4 bits are packed into one hex char—no delimiter.
0000000214000100
Secondary bitmap (also 16 hex).
Present only because bit 1 in the primary bitmap = 1.
Remaining blocks
Data elements in ascending order (2, 3, 4, … ). Each occupies exactly its specified length, or LL/LLL prefix + value.
Padding (zeros / spaces) makes every fixed field keep its place so downstream systems can slice without delimiters.
3. Bitmap → Which Fields Follow?
Convert each hex char to binary. Example:
B23A…→1011 0010 0011 1010 …Number bits 1‑64 (or 1‑128).
If a bit = 1, its corresponding field immediately follows the bitmap(s).
Move through the message in ascending field order, reading:
2 – PAN
LLVAR n
up to 19
LL tells you how many digits follow.
3 – Processing code
n
6
Always 000000 for POS sale in our messages.
4 – Amount, Txn
n
12
Right‑padded zeros: 00000000285 = $2.85
11 – STAN
n
6
185503 in the sample.
37 – Retrieval Ref # (RRN)
an
12
724181349863 – used to link auth ↔ purchase.
41 – Terminal ID
ans
8
00010003 (space‑padded if shorter).
…
(The complete ISO 8583 spec defines > 120 fields. Only the ones lit by the bitmap are present.)
4. Reading Variable‑length Fields
PAN (Field 2) = 16 543464******6993
──┘ └─────────────────
length indicator (2 chars)If the bitmap says Field 2 exists, take the next 2 chars, convert to an int (
16), then read exactly that many chars for the PAN.Immediately after that, continue with the next field (Field 3).
5. Padding Rules Cheat‑Sheet
n (numeric)
right
0
00000000285
an, ans (alpha / alnum / special)
left
space (0x20)
00010003·· → becomes 00010003 <space><space>
Track / discretionary
fixed
F or = etc. as per card standards
543464******6993=...
Tip: When debugging, replace
0x20with·so you can see trailing spaces.
6. Putting It All Together (Walk‑through)
Strip transport header (
ISO0260000700).Read MTI (
0120).Read Primary bitmap (16 hex).
Because bit 1 = 1, read Secondary bitmap (another 16 hex).
Iterate fields:
bit 2 = 1 → Field 2 (LLVAR) → read length LL → read PAN.
bit 3 = 1 → Field 3 (6 n) → read 6 chars.
… continue until all
1bits are consumed.
You should land exactly on the last byte of the message. Extras mean parsing error.
7. Where the Retrieval Reference Number Hides
Field 37 (RRN) always shows up after Field 35/36 (Track2/Track3) for our host.
Because we never carry field 70+ in auth/purchase, the RRN is usually < halfway down the message.
Example auth vs. purchase pair:
Auth – … 185503 | **724181349863** | 0000010003 …
Purchase – … 583719 | **724181349863** | 895229592889 …Same RRN → same transaction lifecycle.
8. Appendix – Field Directory (Common in Our Webhooks)
2
LLVAR (≤ 19)
n
Primary account number (PAN)
3
6
n
Processing code
4
12
n
Amount, transaction
11
6
n
System trace audit number (STAN)
12
6
n
Local Txn time (hhmmss)
13
4
n
Local Txn date (MMDD)
37
12
an
Retrieval reference number (RRN)
41
8
ans
Terminal ID
42
15
ans
Merchant ID (sometimes blank)
43
40
ans
Card acceptor name / location
55
LLLVAR (≤ 999)
b
EMV data (if e‑com / chip)
(Fields differ per processor; consult the host spec if something new appears.)
Last updated