OpenSwitchX

A working ISO 8583 payment switch simulator (iso8583-sim) plus the full dev/deploy tooling around it — Jenkins, Ansible, Linux provisioning, VS Code config, and a browser-based transaction console.

Layout

openswitchx/
├── iso8583-sim/              # the actual app — Java 17 / Maven
│   ├── pom.xml
│   ├── db/schema.sql          # PostgreSQL schema: PAN list + transaction log
│   ├── scenarios-example.csv  # batch test scenarios for the CLI simulator
│   ├── README-app.md          # detailed app-level docs (fields, extending, CLI reference)
│   └── src/main/java/com/sim/iso8583/
│       ├── HostSimulatorServer.java   # the "bank" — listens, approves/declines
│       ├── TerminalSimulatorClient.java, TerminalCliSimulator.java, TerminalGuiSimulator.java
│       ├── WebGuiServer.java + IndexHtml.java   # the browser transaction console (recommended GUI)
│       ├── Iso8583Packer.java, Iso8583Field.java, Iso8583Framing.java   # wire protocol
│       ├── Database.java, TransactionRepository.java   # PostgreSQL persistence
│       └── TokenMetadata.java
│
├── Jenkinsfile                # CI/CD — checkout → build → test → package → optional deploy
├── Makefile                   # setup/build/test/package/run, wraps Maven so Jenkins/VS Code
│                               # never need to know the app's internals
├── ansible/
│   ├── inventory.ini           # staging (localhost by default) + production
│   ├── playbook.yml            # provisions Ubuntu, deploys as a systemd service
│   └── templates/openswitchx.service.j2
├── scripts/setup-linux.sh     # one-shot Ubuntu bootstrap: JDK, Maven, PostgreSQL, driver, firewall
├── .vscode/                   # settings, recommended extensions, tasks, and launch configs
└── web/index.html             # static ops-console mockup (pipeline visual, not the real GUI)

Quickest path to a running system

# 1. Open in VS Code
code openswitchx

# 2. Bootstrap this machine (installs JDK, Maven, PostgreSQL, driver, opens firewall ports)
sudo bash scripts/setup-linux.sh

# 3. Set up the database
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"
sudo -u postgres createdb iso8583
sudo -u postgres psql -d iso8583 -f iso8583-sim/db/schema.sql

# 4. Build
make setup && make build && make test && make package

# 5. Deploy the host simulator as a systemd service (localhost by default)
ansible-playbook -i ansible/inventory.ini ansible/playbook.yml -e target_env=staging -e app_version=1

# 6. Confirm it's running
sudo systemctl status openswitchx
sudo journalctl -u openswitchx -f

See it in the browser (recommended GUI)

make run-gui

Open http://localhost:8080 — a transaction console with a PAN dropdown (live from the database), amount/entry-mode/wallet fields, live stat cards, a continuously updating transaction history table (pulled from PostgreSQL), and a raw ISO 8583 request/response viewer for the last transaction sent.

Or in VS Code: Run and Debug → "Web GUI (port 8089)" (F5).

Send a transaction from the command line instead

cd iso8583-sim
mvn -q -f pom.xml exec:java -Dexec.mainClass="com.sim.iso8583.TerminalSimulatorClient" -Dexec.args="127.0.0.1 9999"

CI — Jenkins

Point a Jenkins Pipeline job at this repo (Pipeline script from SCM); it auto-detects the Jenkinsfile and runs make setup/build/test/package, archives the jar, and — if the RUN_DEPLOY parameter is checked — runs the Ansible playbook.

Everything below iso8583-sim/ is the actual protocol implementation

See iso8583-sim/README-app.md for the ISO 8583 field reference, how to add new fields, CLI simulator flags/presets, and notes on extending toward a secondary bitmap or TLS.