Skip to content
This repository was archived by the owner on Sep 7, 2026. It is now read-only.
bau-wdPublic archive

About

succeeder:

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ISO 8583 Tooling

A web-based DX tool for parsing and visualizing ISO 8583:1993 messages — built with Vanilla JavaScript and Vite.


Features

  • 🧠 Smart Editor — single surface to parse, edit, build, and diff ISO 8583 messages
  • ⚡️ Live rebuilds — MTI + field edits instantly recalc bitmaps and regenerate raw hex
  • 🔍 Inline inspector — view DE names, formats, lengths, values, and raw hex in one grid
  • 🧮 Baseline diff — toggle diff mode to compare against a pasted or current baseline
  • 🗺 Bitmap decoding — primary and secondary bitmaps parsed automatically
  • ⚙️ Skip length headers — optionally skip N leading bytes (e.g., 2-byte or 4-byte headers)
  • 🌐 Alternate encodings — parse/build text fields as ASCII or EBCDIC (CP037)
  • 🧰 CLI parity — parse, export, and build messages from the terminal
  • 📦 Zero backend — runs entirely in the browser
  • 🎨 Color-coded fields by category (card data, auth data, private data)

Getting Started

Prerequisites

Install & Run

git clone https://github.com/bau-wd/iso8583-tooling.git
cd iso8583-tooling
npm install
npm run dev

Open http://localhost:5173 in your browser.

Build for Production

npm run build
# output in dist/
npm run preview

CLI Usage

Install dependencies first (npm install), then run the CLI through npm:

npm run cli -- <command> [options]
# or directly
node ./src/cli.js <command> [options]

Supported commands mirror the web UI features:

  • Parse hex to JSON/table (skip headers supported)
    npm run cli -- parse --hex "<hex>" --skip-bytes 2 --json
    npm run cli -- parse --file message.hex --out parsed.json --json

  • Build hex from a UI-style JSON payload
    npm run cli -- build --file payload.json --out message.hex --summarize

  • Get the built-in sample message
    npm run cli -- sample --summarize
    npm run cli -- sample --json > sample.json

--json writes the same minimal export produced by the UI; --summarize additionally prints the parsed table view. Use --out to write results to a file.


How to Use

  1. Paste or type a hex-encoded ISO 8583 message into the Smart Editor’s raw input. (Click Load Sample to start from a demo message.)
  2. Choose text encoding (ASCII default or EBCDIC CP037) and optionally enable Skip length header to ignore leading bytes.
  3. Click Parse or keep typing — the inspector will populate MTI, bitmaps, and all present data elements.
  4. Edit the MTI or any field value inline. The raw hex bar regenerates automatically with correct length prefixes and bitmaps.
  5. Add fields via the dropdown + Add field, or remove rows directly in the inspector to rebuild the message.
  6. Toggle Diff mode to compare against a baseline: paste a baseline hex (or reuse the current message) and click Parse baseline to see field-level differences.

Sample ISO 8583:1993 Message

The following is a hand-crafted ISO 8583:1993 0200 Authorization Request. Click Load Sample in the app to use it directly; it will be encoded with your currently selected character set (ASCII by default).

Fields present: DE02 (PAN), DE03 (Processing Code), DE04 (Amount), DE07 (Transmission Date & Time), DE11 (STAN), DE12 (Local Time), DE13 (Local Date), DE22 (POS Entry Mode), DE25 (POS Condition Code), DE35 (Track 2), DE41 (Terminal ID), DE42 (Card Acceptor ID), DE49 (Currency Code).


JSON Export Format

{
  "mti": "0200",
  "primaryBitmap": "7238000102C08000",
  "secondaryBitmap": null,
  "fields": {
    "2": {
      "de": 2,
      "name": "Primary Account Number (PAN)",
      "format": "n",
      "lengthType": "LLVAR",
      "length": 16,
      "value": "4111111111111111",
      "rawHex": "34313131313131313131313131313131"
    },
    "3": {
      "de": 3,
      "name": "Processing Code",
      "format": "n",
      "lengthType": "fixed",
      "length": 6,
      "value": "000000",
      "rawHex": "303030303030"
    }
  },
  "errors": []
}

ISO 8583:1993 Field Reference (Summary)

DE Name Format Length Type Max Length
2 Primary Account Number (PAN) n LLVAR 19
3 Processing Code n fixed 6
4 Amount, Transaction n fixed 12
7 Transmission Date & Time n fixed 10
11 System Trace Audit Number n fixed 6
12 Local Transaction Time n fixed 6
13 Local Transaction Date n fixed 4
22 Point of Service Entry Mode n fixed 3
25 Point of Service Condition Code n fixed 2
35 Track 2 Data z LLVAR 37
37 Retrieval Reference Number an fixed 12
38 Authorization Identification Response an fixed 6
39 Response Code an fixed 2
41 Card Acceptor Terminal ID ans fixed 8
42 Card Acceptor ID Code ans fixed 15
48 Additional Data - Private ans LLLVAR 999
49 Currency Code, Transaction an fixed 3
52 PIN Data b fixed 8
55 ICC (EMV) Data b LLLVAR 999
64 MAC b fixed 8

(Full DE1–DE128 definitions are in src/fieldDefinitions.js.)


License

MIT

About

succeeder:

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages