# iso8583sim

> A modern, high-performance ISO 8583 message simulator with a Python SDK, CLI, and LLM-assisted explanation — parse, build, and validate the messaging standard behind every card transaction at 180k+ TPS.

iso8583sim is an open-source (MIT) Python library and command-line tool for working with ISO 8583, the financial-transaction messaging standard used by ATMs, POS terminals, and card networks. It parses, builds, and validates messages; supports six card networks (VISA, Mastercard, AMEX, Discover, JCB, UnionPay); handles EMV / Field 55 BER-TLV chip data; covers ISO 8583 versions 1987, 1993, and 2003; and reaches ~182k parse TPS with optional Cython extensions. It can also explain messages in plain English and generate them from natural language using OpenAI, Anthropic, Google, or local Ollama models.

- Install: `pip install iso8583sim`
- Homepage: https://iso8583sim.com/
- Source: https://github.com/bassrehab/ISO8583-Simulator
- Package: https://pypi.org/project/iso8583sim/
- License: MIT
- Full documentation text (all pages inline): https://iso8583sim.com/llms-full.txt

## Documentation
- [Installation — Getting Started](https://iso8583sim.com/docs/getting-started/installation/)
- [Quick Start — Getting Started](https://iso8583sim.com/docs/getting-started/quickstart/)
- [ISO 8583 Concepts — Getting Started](https://iso8583sim.com/docs/getting-started/concepts/)
- [Overview — Architecture](https://iso8583sim.com/docs/architecture/overview/)
- [Message Flow — Architecture](https://iso8583sim.com/docs/architecture/message-flow/)
- [Module Structure — Architecture](https://iso8583sim.com/docs/architecture/module-structure/)
- [Overview — Core Module](https://iso8583sim.com/docs/core/)
- [Types & Fields — Core Module](https://iso8583sim.com/docs/core/types/)
- [Parser — Core Module](https://iso8583sim.com/docs/core/parser/)
- [Builder — Core Module](https://iso8583sim.com/docs/core/builder/)
- [Validator — Core Module](https://iso8583sim.com/docs/core/validator/)
- [EMV Data — Core Module](https://iso8583sim.com/docs/core/emv/)
- [Object Pool — Core Module](https://iso8583sim.com/docs/core/pool/)
- [Overview — Card Networks](https://iso8583sim.com/docs/networks/)
- [VISA — Card Networks](https://iso8583sim.com/docs/networks/visa/)
- [Mastercard — Card Networks](https://iso8583sim.com/docs/networks/mastercard/)
- [Other Networks — Card Networks](https://iso8583sim.com/docs/networks/others/)
- [Overview — LLM Features](https://iso8583sim.com/docs/llm/)
- [Providers — LLM Features](https://iso8583sim.com/docs/llm/providers/)
- [Message Explainer — LLM Features](https://iso8583sim.com/docs/llm/explainer/)
- [Message Generator — LLM Features](https://iso8583sim.com/docs/llm/generator/)
- [CLI — Reference](https://iso8583sim.com/docs/cli/)
- [API · Core — Reference](https://iso8583sim.com/docs/api/core/)
- [API · LLM — Reference](https://iso8583sim.com/docs/api/llm/)
- [API · Demo — Reference](https://iso8583sim.com/docs/api/demo/)
- [Performance — Reference](https://iso8583sim.com/docs/performance/)
- [Troubleshooting — Reference](https://iso8583sim.com/docs/troubleshooting/)

## Key concepts
- ISO 8583 message = MTI (4-digit message type indicator) + bitmap(s) indicating present data elements + the data elements themselves.
- Data elements (DE) are numbered fields, e.g. DE 2 = PAN, DE 3 = processing code, DE 4 = amount, DE 11 = STAN, DE 55 = EMV/ICC data.
- The library exposes `ISO8583Parser`, `ISO8583Builder`, `ISO8583Validator`, and `ISO8583Message` under `iso8583sim.core`, and `MessageExplainer` / `MessageGenerator` under `iso8583sim.llm`.

## Articles
- [Simulating ISO 8583 messages for testing](https://iso8583sim.com/blog/simulating-iso-8583-for-testing/): You can't point your test suite at Visa. Here's how to simulate ISO 8583 traffic instead — build requests, craft the responses you need (including the ugly declines), and wire it all into pytest and CI.
- [Understanding the ISO 8583 bitmap](https://iso8583sim.com/blog/iso-8583-bitmap/): The bitmap is the cleverest part of ISO 8583 and the first thing that confuses everyone. Here's how to read one by hand — bit numbering, the secondary bitmap, and a full worked example of 7238000108208000.
- [ISO 8583, explained: the format behind every card payment](https://iso8583sim.com/blog/iso-8583-explained/): A plain-English tour of ISO 8583 — the MTI, the bitmap, data elements, and the request/response flow. The 40-year-old message format still running the world's card rails, minus the spec-reading headache.

## Project
- [GitHub repository](https://github.com/bassrehab/ISO8583-Simulator)
- [PyPI package](https://pypi.org/project/iso8583sim/)
- [Author — Subhadip Mitra](https://subhadipmitra.com)