TCP gateway that accepts raw ISO 8583 financial messages, parses them, forwards to a core banking system over HTTP, and returns packed responses with duplicate detection.
Card networks still speak ISO 8583 over raw TCP, while modern core banking systems expose HTTP APIs. This switch sits between the two: it listens for packed ISO 8583 messages, parses the MTI, bitmaps, and data elements, translates each transaction into an HTTP call to the core banking system, and packs the answer back into ISO 8583 for the terminal. The walkthrough below follows every message flow the switch handles.
The gateway starts a TCP listener on port 8583, reads the two-byte length prefix, and receives a packed 0200 financial request. It parses the message, extracts the STAN and transaction details, forwards them to the core banking system's financial endpoint, and completes the leg with an approved response code 00.
Each MTI maps to its own core banking endpoint and timeout, and the mapping lives in the database. A 0100 authorization goes to the authorize endpoint with a 15 second budget, a 0200 financial request gets 30, and the terminal receives its answer in the packed response.
When a terminal times out or a customer cancels, a 0400 reversal arrives. The switch locates the original transaction, forwards the reversal to the core banking system's reversal endpoint, and confirms with a 0410 so both sides agree the money never moved.
Failures translate cleanly: when the core banking system reports insufficient funds, the switch packs response code 51 back to the terminal. Retried messages reusing an already-seen STAN within the duplicate window are answered with code 94 and dropped, so a flaky terminal cannot double-post a transaction.
PANs are masked to first-six and last-four everywhere they are logged, and PIN blocks pass through as opaque binary. Messages carrying a MAC in field 64 are verified with HMAC-SHA256, so a tampered message is rejected before it reaches the core.
Every field definition (fixed, LLVAR, or LLLVAR, in ASCII, BCD, or binary) is a row in the FieldDefinitions table, seeded with twenty standard fields from PAN to EMV ICC data. Adding or changing a field is a database edit, not a parser rewrite and redeploy.
Terminals and hosts exchange 0800 network management messages to confirm the link is alive. The switch answers echo tests locally with an 0810 in milliseconds, without touching the core banking system.
Not everything arriving on a payment port is a valid message. When parsing fails, the switch rejects the message, logs exactly where the parse broke, and keeps the connection alive for the next message instead of dropping the terminal.
One docker compose command brings up SQL Server, a mock core banking system, and the gateway. A Python test client sends real packed messages over TCP, and a Swagger console builds and converts BCD payloads, so the whole flow is testable without touching a real bank.