Educational payment system simulator covering bank-side infrastructure: switching, ISO 8583 routing, HSM cryptography, and interbank communication. Built for corporate training and as a YouTube tutorial series.
This simulator covers what happens inside the bank's infrastructure — the layers that production payment apps (gateway, disbursement) never touch.
| Topic | Covered Here |
|---|---|
| ISO 8583 protocol internals | Yes |
| Payment switching / BIN routing | Yes |
| HSM / key management / PIN blocks | Yes |
| MAC validation / generation | Yes |
| Network management (sign-on, echo, key exchange) | Yes |
| SNAP API / bank integration | No (see payment-gateway) |
| Virtual account / QRIS collection | No (see payment-gateway) |
| Bulk transfer / disbursement | No (see disbursement-platform) |
5 components. 3 already exist, 2 are new builds in this repo.
graph TD
ATM["ATM SIMULATOR<br/>(terminal)<br/><i>EXISTS</i>"]
SWITCH["PAYMENT SWITCH<br/><b>NEW</b>"]
ATM_SERVER["ATM SERVER<br/>(Issuer Bank)<br/><i>EXISTS</i>"]
HSM["HSM SIMULATOR<br/><i>EXISTS</i>"]
DASHBOARD["MONITORING DASHBOARD<br/>(real-time transaction flow visualization)<br/><b>NEW</b>"]
ATM -- "ISO 8583" --> SWITCH
SWITCH -- "ISO 8583" --> ATM
SWITCH -- "ISO 8583" --> ATM_SERVER
ATM_SERVER -- "ISO 8583" --> SWITCH
SWITCH <-- "REST API" --> HSM
SWITCH -- "WebSocket" --> DASHBOARD
| # | Component | Status | Repo | Description |
|---|---|---|---|---|
| 1 | HSM Simulator | Exists | artivisi/hsm-simulator | Key management, PIN encryption, MAC generation. Spring Boot 3.5, Java 21, PostgreSQL 17. |
| 2 | ATM Server (Issuer) | Exists | artivisi/workshop-spring-jpos-atm-server | Bank server: balance inquiry, withdrawal, PIN validation via HSM. Spring Boot 4, Java 25, jPOS 3.0. |
| 3 | ATM Simulator (Terminal) | Exists | artivisi/workshop-spring-jpos-atm-simulator | ATM terminal UI: card entry, PIN input, transaction flow. Spring Boot 3.5, Java 25, jPOS 3.0, Thymeleaf + Tailwind. |
| 4 | Payment Switch | New | This repo | Central routing engine. Routes ISO 8583 between terminals and issuers. |
| 5 | Monitoring Dashboard | New | This repo | Real-time web UI showing transaction flow across the network. |
The core new build. Demonstrates the infrastructure layer between terminals and banks.
Capabilities:
- Receives ISO 8583 messages from terminals (ATM Simulator)
- Routes to correct issuer based on BIN (Bank Identification Number) routing table
- Calculates and applies interchange fees
- Logs every transaction with full ISO 8583 message dumps
- Validates MAC on incoming messages via HSM Simulator
- Generates MAC on outgoing messages via HSM Simulator
- Manages terminal sign-on/sign-off
- Handles network management messages (echo test, key exchange)
- Publishes transaction events to Monitoring Dashboard via WebSocket
ISO 8583 message types:
- 0200/0210 — Financial transaction (balance inquiry, withdrawal)
- 0400/0410 — Reversal
- 0800/0810 — Network management (sign-on, echo, key exchange)
Key modules:
| Module | Purpose |
|---|---|
RoutingEngine |
BIN-based routing table, determines destination for each transaction |
FeeCalculator |
Configurable fee rules per transaction type, acquirer, terminal |
TransactionLogger |
Persists every message with timestamp, source, destination, response code |
SwitchParticipant |
Core jPOS TransactionParticipant processing pipeline |
MacValidator |
Calls HSM Simulator REST API to verify/generate MAC |
NetworkManager |
Handles sign-on, echo, key exchange |
Real-time web dashboard — the visual centerpiece for YouTube demos and training sessions.
Sections:
-
Network Map — SVG diagram of connected components (HSM, ATM, Switch, Issuer). Live status indicators. Animated lines showing transaction flow direction and timing.
-
Transaction Feed — Real-time scrolling list. Each row: timestamp, source, destination, MTI, processing code, amount, response code, latency. Color-coded: green (approved), red (declined).
-
Message Inspector — Click any transaction to see raw ISO 8583 message breakdown: bitmap visualization, data element table, request vs response side-by-side.
-
Statistics Panel — TPS gauge, success/failure ratio, average response time, transaction count by type.
| Layer | Technology | Version |
|---|---|---|
| Language | Java | 21+ |
| Framework | Spring Boot | 3.x |
| ISO 8583 | jPOS | 3.0 |
| Database | PostgreSQL | 17 |
| Migration | Flyway | latest |
| Security | Bouncy Castle | latest |
| Frontend | Thymeleaf + Tailwind CSS + HTMX | latest |
| Real-time | Spring WebSocket | (included in Spring Boot) |
| Container | Docker Compose | latest |
| Build | Maven | 3.9+ |
| Testing | JUnit 5, Testcontainers | latest |
git clone https://github.com/artivisi/payment-simulator.git
cd payment-simulator
docker compose upOnce running, access:
| Component | URL / Port |
|---|---|
| Monitoring Dashboard | http://localhost:9000 |
| ATM Simulator | http://localhost:8030 |
| HSM Simulator | http://localhost:8010 |
| ATM Server | http://localhost:8020 |
| Payment Switch (ISO 8583) | port 33333 |
| Payment Switch (HTTP) | http://localhost:8040 |
| PostgreSQL | port 5432 |
- Open ATM Simulator (http://localhost:8030)
- Insert card, enter PIN
- Select withdrawal, enter amount
- Watch the Monitoring Dashboard (http://localhost:9000):
- ATM Simulator sends 0200 to Payment Switch (port 33333)
- Switch validates MAC via HSM Simulator
- Switch routes to ATM Server (issuer) based on BIN
- ATM Server validates PIN via HSM Simulator
- ATM Server checks balance, approves/declines
- Response flows back through the switch
- Dashboard shows each hop with timing data
- Click the transaction in the feed to inspect the full ISO 8583 message at each hop
payment-simulator/
├── docker-compose.yml # Orchestrates all 5 components
├── payment-switch/ # New: routing engine
│ ├── src/
│ └── pom.xml
├── monitoring-dashboard/ # New: real-time web UI
│ ├── src/
│ └── pom.xml
├── pom.xml # Parent POM
└── docs/
├── architecture.md
└── iso8583-message-spec.md
Existing components (HSM Simulator, ATM Server, ATM Simulator) are pulled as Docker images. This repo contains the switch, dashboard, and the Docker Compose that ties everything together.
This simulator is built live on camera as Part 1 of a 3-part YouTube series.
| Ep | Title | Build Target |
|---|---|---|
| 1 | Arsitektur Sistem Pembayaran Indonesia | Whiteboard: terminals, acquirer, switch, issuer, HSM, settlement |
| 2 | ISO 8583: Bahasa Transaksi Perbankan | MTI, bitmap, data elements. Live demo with jPOS |
| 3 | HSM: Keamanan di Balik Setiap Transaksi | PIN blocks, key hierarchy. Demo HSM Simulator |
| 4 | Payment Switch: Jantung Sistem Pembayaran | Build the switch. BIN routing, MAC validation, transaction logging |
| 5 | Monitoring Dashboard: Melihat Transaksi Real-time | Build the dashboard. End-to-end demo |
Apache License 2.0