Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

ISO 8583 Operations

This document covers two related pipeline operations used for ISO8583 processing:

  • HexMessageRouterOperation

  • ReplaceISOOperation

Together, they are commonly used to:

  1. identify the kind of incoming ISO message

  2. choose the correct sub-pipeline for that message

  3. parse the ISO payload

  4. redact or reveal selected ISO fields

Flow Diagram

HexMessageRouterOperation

HexMessageRouterOperation is a conditional dispatcher.

It:

  1. converts the incoming payload bytes into a hex string

  2. compares that hex string against configured route keys

  3. runs the matching nested pipeline for any matching route

  4. optionally runs a defaultPipeline

It does not parse ISO fields directly. It routes based on raw payload hex.

How Routing Works

Each route key represents the MTI. A route matches if either:

  • the payload hex starts with the route key

  • the payload hex contains the route key and checkContains is enabled

Conceptual example:

In this example:

  • 0200 is ASCII for 30323030

  • if the payload starts with 0200, the router runs the nested ISO pipeline and processes the payload based on the JPOS packager config.

Does It Route On MTI?

Not inherently.

HexMessageRouterOperation operates on the entire payload as raw bytes converted to hex. It only becomes "MTI routing" if the configured route key corresponds to the MTI bytes at the start of the payload.

For ISO8583, that is a common setup:

  • 0200 -> hex 30323030

  • 0800 -> hex 30383030

If the MTI is not at byte 0 because the payload has a transport header, another operation usually runs first to remove or skip that header. For example, a SkipBytesOperation may be used so the MTI becomes the first visible bytes before routing.

Common Pattern

A common ISO flow is:

  1. skip transport/header bytes if needed

  2. route by MTI using HexMessageRouterOperation

  3. parse the ISO payload with ReplaceISOOperation

  4. redact or reveal selected fields

ReplaceISOOperation

ReplaceISOOperation is a reversible pipeline step that:

  1. Unpacks an ISO8583 message using a configured jPOS packager.

  2. Extracts one or more configured ISO fields.

  3. Sends each extracted field value through the rest of the pipeline.

  4. Writes the downstream result back into the same ISO field.

  5. Re-packs the ISO message and returns it.

This means ReplaceISOOperation does not tokenize or reveal values by itself. It only isolates ISO fields and hands them to later operations such as RedactOperation or RevealOperation.

How It Works

For each field listed in fields:

  • ReplaceISOOperation reads the field value from the unpacked ISOMsg.

  • It calls next(fieldValue), which passes that value to downstream operations.

  • When the downstream operations return, inverse() writes the returned bytes back into the current field.

As a result:

  • If the downstream pipeline returns a token, the ISO field becomes a token.

  • If the downstream pipeline returns cleartext, the ISO field becomes cleartext.

Configuration

The operation is configured with ReplaceISOOperationConfig.

Fields

  • fields: ISO field numbers to extract and process.

  • charset: used when converting values to and from bytes. If blank, the code defaults to ISO-8859-1.

  • originalPackager: base64-encoded jPOS GenericPackager XML used to unpack the incoming ISO message.

  • processedPackager: base64-encoded jPOS GenericPackager XML used to pack the outgoing ISO message.

  • skipIfFieldNotFound: if false, a missing field causes an error. If true, the field is skipped.

What The Packager Does

The packager is the schema for the ISO message. It tells jPOS how to interpret raw bytes:

  • which fields exist

  • whether a field is fixed-length or variable-length

  • whether a field is numeric, character, or binary

  • how long the field is

  • how nested components should be parsed

A simple decoded packager XML looks like this:

In that example:

  • field 0 is a 4-digit numeric MTI

  • field 1 is the bitmap

  • field 2 is an LLVAR numeric field up to 19 digits

  • field 3 is a fixed 6-digit numeric field

For field 2, a wire value like:

means:

  • 16: the field length prefix

  • 4111111111111111: the actual PAN

Without the packager, the system would not know how to split those bytes correctly.

Redaction Flow

When used with RedactOperation, the field value is tokenized.

Example Pipeline

Example Input / Output

Input ISO field:

Downstream redactor result:

Output ISO field after re-pack:

Conceptual Processing Steps

  1. Unpack the ISO message with originalPackager.

  2. Extract field 2.

  3. Pass 4111111111111111 to RedactOperation.

  4. Receive tok_sandbox_abc123.

  5. Write tok_sandbox_abc123 back into field 2.

  6. Re-pack the ISO message with processedPackager.

Reveal Flow

When used with RevealOperation, the token is de-tokenized.

Example Pipeline

Example Input / Output

Input ISO field:

Downstream reveal result:

Output ISO field after re-pack:

Conceptual Processing Steps

  1. Unpack the ISO message with originalPackager.

  2. Extract field 2.

  3. Pass tok_sandbox_abc123 to RevealOperation.

  4. Receive 4111111111111111.

  5. Write 4111111111111111 back into field 2.

  6. Re-pack the ISO message with processedPackager.

Important Clarification

ReplaceISOOperation is not the tokenization engine.

It only:

  • parses the ISO message

  • extracts the configured fields

  • routes those field values through downstream operations

  • writes the returned value back into the message

The actual tokenization or reveal logic is performed by the configured redactor behind RedactOperation or RevealOperation.

PreviousTCP Proxy (ISO8583)
NextAPI Reference

Last updated