ISO8583 to JSON: Why Your API Gateway Cannot Do This Alone and What to Use Instead
Category: ISO8583 Converter Target reader: CTO, Tech Architect, Payments Consultant Keywords: ISO8583 to JSON API gateway, ISO8583 binary translation, parse ISO8583 messages, ISO8583 converter architecture, API gateway payment integration
When architects first encounter the problem of connecting a modern application stack to an ISO8583 payment network, a reasonable question comes up quickly: can our existing API gateway handle the translation?
It is a sensible instinct. API gateways are designed to mediate between systems with different interfaces. Kong, AWS API Gateway, Azure API Management, NGINX, Apigee — these are mature, capable products that handle authentication, routing, rate limiting, protocol mediation, and payload transformation as core functions. If the job is "take something from one format and deliver it in another," the API gateway seems like the obvious place to put that logic.
It is the wrong tool for this specific job, and understanding precisely why is important — not to dismiss the API gateway, but because the architectural mistake of trying to force this translation through one has real consequences for timelines, reliability, and production stability.
What API Gateways Are Actually Built For
To understand the limitation, it helps to be precise about what API gateways do well.
API gateways are designed to mediate between systems that share a common transport layer — overwhelmingly HTTP and HTTPS — but differ in their authentication mechanisms, routing rules, rate limiting requirements, or payload schemas. The transformation capabilities built into most gateways are designed for the kinds of differences that exist between HTTP-based systems: renaming JSON fields, restructuring a JSON object, converting between JSON and XML, adding or removing headers, translating query parameters to body fields.
These are text-based, schema-driven transformations. The gateway receives an HTTP request with a known content type, applies a transformation rule expressed in a templating language or a mapping configuration, and forwards the result as another HTTP request. The input and output are both structured text. The transport is stateless HTTP in both directions.
ISO8583 breaks every one of those assumptions simultaneously.
Why ISO8583 Is Not an HTTP Protocol Problem
ISO8583 is not an HTTP protocol. This is the foundational incompatibility that makes an API gateway the wrong tool, and it goes deeper than it might first appear.
The transport layer is TCP, not HTTP. ISO8583 messages travel over persistent, stateful TCP socket connections. The connection is established once and kept alive for the duration of the session. There is no request-response cycle in the HTTP sense — there is a bidirectional byte stream over which structured messages flow in both directions, with message boundaries delimited by a length indicator prepended to each message rather than by HTTP framing. An API gateway that sits in front of an HTTP service cannot terminate a TCP socket connection to a card scheme host. The transport layer is categorically different.
The message format is binary, not text. ISO8583 messages are binary-encoded structures. The first component is a message type indicator — a 4-digit BCD or ASCII code identifying the message class and function. The next component is a bitmap — either 8 bytes (64 bits) for a primary bitmap or 16 bytes (128 bits) if a secondary bitmap is also present — where each bit indicates whether the corresponding data element is present in the message. Following the bitmap are the data elements themselves, each encoded according to its own type definition: fixed-length or variable-length, numeric or alphanumeric or binary, ASCII or EBCDIC or BCD or packed binary.
There is no content-type header. There is no schema document the gateway can reference. There is no delimiter between fields. The only way to know where one field ends and the next begins is to read the bitmap to determine which fields are present, then apply the field definition table to know the encoding and length of each one in sequence. That process requires a purpose-built ISO8583 parser — it cannot be expressed as a gateway transformation rule.
The session is stateful. HTTP gateways are designed around stateless request-response semantics. ISO8583 sessions are stateful in multiple dimensions. The TCP connection itself is stateful and must be maintained continuously — card scheme hosts send echo messages on a regular interval (typically every 60 seconds) and consider a connection unhealthy if they do not receive timely responses. Message correlation is stateful — each outbound message carries a Systems Trace Audit Number that must be matched to the corresponding inbound response, which may arrive out of order under load. Reversal flows are stateful — a reversal message must correctly reference the original authorization message. None of this maps onto the stateless HTTP model that API gateways are built around.
What Happens When Teams Try It Anyway
Despite these incompatibilities, teams do attempt to push ISO8583 translation through API gateways, usually in one of two configurations. Understanding why both fail is useful.
Configuration 1: Custom plugin or transformation script in the gateway. Some API gateways support custom plugins or scripting — Kong's plugin architecture, AWS API Gateway's Lambda integration, NGINX's Lua support. Teams sometimes attempt to write ISO8583 parsing logic as a gateway plugin, receiving a JSON payload from the application, transforming it to ISO8583, and forwarding it over a TCP connection managed within the plugin.
The problem is that this moves the entire ISO8583 implementation into the gateway layer, where it does not belong and where the gateway's tooling does not support it well. TCP connection management in a gateway plugin is fragile — the gateway is not designed to maintain long-lived stateful socket connections per upstream host. The plugin has to implement ISO8583 field encoding from scratch in whatever scripting language the gateway supports. The result is a bespoke ISO8583 implementation living inside a gateway plugin, with all the maintenance burden and fragility that implies, plus the added complexity of the gateway's own plugin lifecycle management.
Configuration 2: Pre-processing service with the gateway handling routing only. A more architecturally aware approach is to build a separate translation service, put the ISO8583 logic there, and use the API gateway only for routing. This is conceptually correct — it recognizes that the gateway cannot do the translation — but it means you are still building the ISO8583 translation service from scratch, which brings back all the timeline and expertise problems described in earlier articles. The gateway's role in this architecture becomes trivial (just route to the translation service), so it adds complexity without solving the core problem.
Neither configuration makes the API gateway the right tool. The first makes it the wrong tool used wrongly. The second makes it an unnecessary layer on top of the right solution.
The Specific Technical Gap in Detail
To be concrete about what an API gateway cannot do, here is the sequence of operations required to translate a JSON authorization request into a valid ISO8583 message and send it to an acquiring host:
Step 1 — Field resolution. The JSON payload from the application contains business-level fields: card number, amount, currency, merchant ID, terminal ID, transaction type. Each of these must be resolved to the correct ISO8583 data element number according to the host's field definition table. This requires knowledge of the host's specific field mapping, including any custom usage of private-use fields (typically fields 60–63).
Step 2 — Field encoding. Each resolved field must be encoded according to its ISO8583 type definition. A numeric field goes in as packed BCD or ASCII digits depending on the host's specification. A variable-length field requires a length prefix encoded as LLVAR (two ASCII digits representing the field length) or LLLVAR (three ASCII digits). An amount field requires the decimal point to be removed and the value zero-padded to the required fixed length. A binary field is passed through as raw bytes. These encoding rules differ per field and per host dialect.
Step 3 — Bitmap construction. Once the set of fields to be included in the message is known, the bitmap must be constructed by setting the bit position corresponding to each present field. If any field above position 64 is present, the secondary bitmap must also be included and bit 1 of the primary bitmap must be set to signal its presence. The bitmap is then encoded as 8 or 16 raw bytes and prepended before the field data.
Step 4 — Message type indicator. The correct 4-digit message type indicator must be prepended before the bitmap. For a standard authorization request, this is 0100. For a reversal, 0400. For a network management message, 0800. The correct value depends on the message class and function being performed.
Step 5 — Length prefix. The complete ISO8583 message — MTI, bitmap, and fields — is prefixed with a length indicator, typically a 2-byte or 4-byte binary value representing the total message length in bytes. This allows the receiving host to read exactly the right number of bytes from the TCP stream to extract a single complete message.
Step 6 — TCP transmission. The framed message is written to the persistent TCP socket connected to the host. The connection must already be established and healthy — confirmed by the most recent successful echo message exchange — before the authorization message is sent.
Step 7 — Response correlation and parsing. The host sends back a response message — ISO8583 message type 0110 — on the same TCP connection. The response must be read from the socket, framed by its length prefix, parsed through the same bitmap-and-field-definition process, and correlated back to the original request by matching STAN values. The parsed field values are then assembled into a JSON response payload and returned to the application.
There is no step in this sequence that an API gateway can perform. The gateway has no TCP socket to the host. It has no bitmap construction logic. It has no field encoding rules. It has no STAN correlation state. It has no echo message handler keeping the connection alive between transactions.
Every step requires a purpose-built ISO8583 handler.
What the Right Architecture Looks Like
The correct architecture separates concerns cleanly: your application stack communicates with a dedicated ISO8583 converter over a standard interface — REST, JSON over HTTP — and the converter owns everything from that interface outward to the card scheme.
Your application sends a JSON authorization request to the converter's REST endpoint. The converter performs all seven steps described above — field resolution, encoding, bitmap construction, MTI assignment, framing, TCP transmission, and response parsing — and returns a JSON response to your application with the authorization result, response code, and any relevant data elements.
From your application's perspective, this is a standard JSON API call. The ISO8583 complexity is completely encapsulated inside the converter. Your API gateway, if you have one, can sit in front of your application services as it normally would — handling authentication, routing, rate limiting — without any involvement in the payment protocol layer at all. Each tool does what it is designed to do.
The converter is not a workaround or a compromise. It is the correct architectural component for this specific function. Just as you would not use an API gateway as a database, you would not use it as an ISO8583 protocol handler. The right tool exists, is purpose-built for exactly this problem, and slots into your existing architecture without requiring changes to anything else.
What This Means for Your Existing Infrastructure
One concern architects raise when evaluating a converter is whether it requires replacing or restructuring existing infrastructure. The answer is no, and the reason is precisely the clean interface boundary described above.
The converter is a service — a deployable process that runs alongside your existing application services. It exposes a REST endpoint on your internal network. Your application services call that endpoint. The converter manages its own TCP connection to the card scheme host. Nothing in your existing stack needs to change: not your API gateway, not your service mesh, not your load balancer, not your database, not your message broker if you use one.
If your existing gateway handles routing to internal services, the converter is just another internal service. If your existing gateway handles authentication, that authentication covers the call from your application to the converter as it would any internal service call. The gateway's responsibilities do not expand. The converter's responsibilities are entirely new, covering the protocol layer that the gateway never touched.
This is the key architectural virtue of a purpose-built converter: it fills the gap without displacing or complicating what already works.
The Gateway Is Not the Problem
Nothing in this article is a criticism of API gateways. They are excellent tools for the problems they are designed to solve, and in a payment integration architecture, they continue to play their appropriate role — mediating HTTP traffic, handling auth, managing routing between application services.
The point is specifically that ISO8583-to-JSON translation is not in their designed problem space, and treating it as if it were leads to one of two outcomes: a fragile bespoke implementation forced into a layer that cannot support it well, or a recognition that a separate translation service is needed anyway, at which point the question becomes whether to build it or deploy a purpose-built one.
The converter is the purpose-built one. It handles exactly the protocol translation problem that the gateway cannot, integrates cleanly with everything the gateway does handle, and requires no ISO8583 expertise from your team to operate.
Want to see how a converter integrates with your existing gateway and service architecture? neaPay engineers can walk through your specific stack — gateway, services, hosting environment — and show you exactly where the converter sits and what the integration looks like end to end. No protocol knowledge required from your side.
