ISO-8583 Toolkit

Unified package for building, parsing, and validating ISO-8583 financial messages. Developer-friendly: 3 core methods, clean facade, real CLI.

---

Quickstart

from iso8583_toolkit import build, parse, validate

# Build
result = build("0100", {
    2: "1234567890123456",
    3: "000000",
    4: "000000001000",
    11: "000001",
})
print(result.message)

# Parse
parsed = parse(result.message)
print(parsed.data_elements)

# Validate
vr = validate("0100", {2: "1234...", 3: "000000"})
print(vr.valid, vr.errors)

CLI

iso8583 parse "0100F230040102B00000..."
iso8583 build 0100 -d 2=1234567890123456 -d 3=000000 -d 4=000000001000 -d 11=000001
iso8583 pp "0100F23004..."
iso8583 validate 0100 -d 2=1234 -d 3=000000
iso8583 mti 0100

---

Setup

cd python-8583
pip install -e .

No external dependencies beyond the Python standard library.

---

Guide

Three core methods

Method	Purpose
build(mti, data_elements)	Build message → BuildResult
parse(message)	Parse message → ParsedMessage
validate(mti, data_elements)	Validate before build → ValidationResult

Typed results

• BuildResult: .message, .bitmap_hex, .mti_parsed, .present_fields
• ParsedMessage: .mti, .data_elements, .parsed_composites, .bitmap_hex
• ValidationResult: .valid, .errors, .warnings

Defaults

• Bitmap: 128-bit (primary + secondary)
• Bitmap length: auto-detected when parsing
• MTI validation: on by default in build()

Examples

See examples/ for:

• auth_flow.py – 0100 → 0110 authorization
• parse_and_pp.py – parse and pretty-print
• socket_client.py – TCP client

---

API Reference

from iso8583_toolkit import build, parse, validate

Errors

• ParseError – invalid message structure
• ConstructorError – invalid build (MTI, DEs)

---

Advanced

Binary DEs (52, 55, 64, 65, 96, 128)

Hex strings; even length; fixed-length DEs enforced.

build("0100", {..., 64: "0123456789ABCDEF0123456789ABCDEF"})

Composite DEs (48, 63, 127)

from iso8583_toolkit.dbm import build_composite, parse_composite

comp = build_composite(48, {1: "USD", 2: "hello", 3: "12345678901"})
subfields = parse_composite(48, comp)

TLV (DE 55 / EMV)

from iso8583_toolkit.tlv import parse_tlv, parse_tlv_tree, pretty_print_tree

tlv_list = parse_tlv("9F2608123456789012345678")
tree = parse_tlv_tree("770482025800")
print(pretty_print_tree(tree))

Sockets

from iso8583_toolkit import build, parse
from iso8583_toolkit.socket_client import Iso8583Client
from iso8583_toolkit.socket_server import Iso8583Server

Custom spec / full toolkit

from iso8583_toolkit.api import ISO8583Toolkit
from iso8583_toolkit.spec_adapter import SpecAdapter

spec = {2: {"len_type": "llvar", "max_len": 19}}
tk = ISO8583Toolkit(spec=spec)