Host Simulator

Overview

The Host Simulator in ISO8583Studio acts as a payment host simulator for development and testing. It accepts incoming connections from POS terminals, ATMs, or other financial clients and returns configurable responses based on matching rules. This eliminates the need for a real host environment during development and QA testing.

Quick Start Guide

Follow these steps to get a basic host simulator up and running:

1. Create a new simulator — From the Home screen, navigate to Simulator → Host Simulator and create a new configuration.
2. Choose a Gateway Type — Select Server to accept incoming connections, Client to connect outward, or Proxy to bridge two sides.
3. Configure Transmission Settings — Set the IP address, port, connection type (TCP/IP or REST), and message length type.
4. Configure the ISO8583 Template — Open the ISO8583 Template tab and import a YAML template via Upload YAML, or build the bit definitions manually. Save with the top-bar Save button.
5. Add Transactions and Responses — In the Settings tab, click + in the transaction list to add a transaction (Description, MTI, Processing Code). Select it, then in the right panel use the Fields tab to set the response field values, the Config tab for transaction-level options, and the API tab for REST matching. Click Save All in the header.
6. Start the Simulator — Open the ISO8583 Transaction tab and click Start. Incoming traffic appears live in the request / response split view.

Gateway Types

The host simulator supports three gateway modes, each suited to different testing scenarios:

Gateway Configuration

The Gateway Type tab provides the core configuration for your simulator instance.

Basic Settings

Response Delay

Control how quickly the simulator responds to incoming requests. Useful for simulating real-world network conditions.

Performance Settings

• Max Concurrent Transactions — Limit the number of simultaneous transactions the simulator will process.
• Detailed Logging — Enable verbose logging for debugging purposes.

Transmission Settings

Configure how the simulator communicates over the network. Settings differ based on your gateway type.

Incoming Connection (Server / Proxy)

Configure the listener that accepts incoming connections:

• IP Address — Bind address (e.g. 0.0.0.0 for all interfaces, or a specific IP).
• Port — TCP port to listen on.
• Message Length Type — How message boundaries are determined.
• Max Concurrent Connections — Limit on simultaneous client connections.
• Timeout — Connection idle timeout in seconds.

Outgoing Connection (Client / Proxy)

Configure the connection to the destination host:

• Target Address — Hostname or IP of the target.
• Target Port — Port to connect to.
• Terminate on Error — Whether to close the connection on errors.

Message Length Types

Connection Types

The simulator supports multiple connection protocols for maximum flexibility:

Message Formats

The simulator can handle multiple message encoding formats for both source and destination.

ISO8583 Formats

REST Message Formats

When using REST connections, the following content types are supported:

• JSON — Application/json content type
• XML — Application/xml content type
• HEX — Hex-encoded message body
• BASE64 — Base64-encoded message body
• BINARY — Raw binary body
• FORM_DATA — Multipart form data

Format Mapping

For non-binary formats (JSON, XML, PlainText), use the Format Mapping Config in the ISO8583 Template tab to map ISO8583 fields to JSON keys, XML elements, or delimited fields.

Log Settings

Configure how the simulator logs transactions and connections.

ISO8583 Transaction Tab

The ISO8583 Transaction tab (visible for Server and Proxy gateway types) is the main runtime interface for controlling and monitoring the simulator.

Controls

• Start / Stop — Launch or shut down the simulator server.
• Hold Message — When enabled, the simulator will not auto-respond. Responses are sent only when you manually click "Send" or after a configurable delay. Useful for inspecting requests before responding.

Live View

The transaction view provides real-time visibility into all traffic:

• Formatted View — Parsed ISO8583 fields shown in a readable table.
• Raw Hex View — Full hexadecimal dump of the message bytes.
• Request / Response Split — Side-by-side view of incoming request and outgoing response.

Transaction Rules (Settings Tab)

Transaction rules define how the simulator matches incoming requests and what responses to return. Configure them in the Settings tab.

Settings Tab Layout

• Header bar — Field info, Export, Import, Save All, plus a Source / Destination toggle (Server simulators default to Source; Proxy mode lets you stage rules for either side).
• Left panel: Transaction list — Add, edit, duplicate, delete transactions. Click a row to select it.
• Right panel: Per-transaction tabs — Fields, Config, and (REST connections only) API.

Adding a Transaction

1. Click + at the top of the transaction list. The Add Transaction dialog opens.
2. Fill in Description * (e.g. Purchase Transaction).
3. Fill in MTI * (e.g. 0200).
4. Fill in Processing Code * (e.g. 000000; use * as a wildcard for any code).
5. Click Save. The new transaction appears in the list.

Setting up the Response (Fields tab)

1. Select the transaction in the left list.
2. Open the Fields tab on the right.
3. Click Add Fields to pick which ISO 8583 bits the response should contain.
4. For each added field, type its response value. Use placeholders — [SV] echoes the request value, [TIME] generates a timestamp, [RAND] generates random digits.
5. Click Save All in the header bar to persist the rules.

Per-Transaction Config & API tabs

• Config tab — Transaction-level options such as response delay overrides and conditional logic.
• API tab (REST connections only) — API Path, request matchers (key path / operator / value), response mappers, and headers.

Matching Logic

When a request arrives, the simulator evaluates rules in order:

1. Parse the incoming message to extract MTI and processing code (Field 3).
2. Compare against each configured transaction rule.
3. The first matching rule wins and its response fields are used to build the response.

Example Rule

Description:     Purchase Transaction
MTI:             0200
Processing Code: 000000

Response Fields (Fields tab):
  Field 39 (Response Code):     00
  Field 38 (Auth Code):         [RAND]
  Field 11 (System Trace):      [SV]
  Field 37 (RRN):               [SV]
  Field 12 (Local Time):        [TIME]
  Field 13 (Local Date):        [TIME]

Dynamic Placeholders

Use placeholders in response field values to generate dynamic content at runtime instead of static values.

REST API Matching

When using REST connections, the simulator provides advanced request matching beyond MTI/processing code.

Match Criteria

• Path — Match the URL path exactly or use * as a wildcard.
• HTTP Method — Match by GET, POST, PUT, DELETE, etc.
• Query Parameters — Match by URL query parameters.
• Headers — Match by HTTP request headers.
• Body Fields — Match by fields in the request body (JSON/XML).

Match Operators

Each matcher supports these comparison operators:

Response Mapping

For REST responses, use Response Mapping to define which fields appear in the response body and headers:

• targetKey — JSON/XML key in the response body.
• value — Static value or placeholder ([SV], [TIME], [RAND]).
• targetHeader — Set a response HTTP header instead of a body field.

ISO8583 Template Tab

The ISO8583 Template tab defines the message specification used for parsing and building messages.

Top-bar actions

• Save — Persist template changes. Send Message and other tabs re-sync immediately.
• Upload YAML — Import a YAML template (the fastest way to bootstrap a known message spec).
• Download Template — Export the current template to YAML.

Per-Bit Editor

Click any bit number to edit it in a side dialog with three required attributes:

• Bit Length — Maximum length (in bytes or characters depending on type).
• Bit Type — Field type (numeric, alphanumeric, binary, etc.).
• Max Length — Used together with the length type (fixed, LLVAR, LLLVAR, LLLLVAR).

Add or remove bits with the Add / Delete buttons.

Template-level Options (toggles)

• Iso8583 use Ascii — Treat numeric fields as ASCII rather than packed BCD.
• Don’t use TPDU Header — Skip the 5-byte TPDU prefix.
• Respond same message if unrecognized — Echo unmatched requests instead of returning an error.
• Metfone message — Enable Metfone-specific framing.
• Not update screen — Suppress UI updates for high-throughput tests.

Unsolicited Messages

Unsolicited messages are messages sent outside the normal request-response flow, typically for network management, notifications, or terminal updates.

Send Message (Client / Proxy)

Craft and send outbound unsolicited messages to connected hosts. Available in Client and Proxy modes. Use the message builder to construct ISO8583 messages with specific fields and send them on demand.

Receive Unsolicited (Server / Proxy)

In Server and Proxy modes, incoming unsolicited messages from clients are displayed in the Unsolicited Message tab. Messages are parsed using the active ISO8583 template.

Security Options

The simulator supports several security features for testing encrypted and authenticated connections.

Cipher Types

Cipher Modes

ECB, CBC, CFB, OFB, and CTS modes are available for block cipher operations.

Authentication

• None — No authentication required.
• Single Password — One shared password for all clients.
• Client Password — Per-client authentication credentials.

SSL/TLS

Enable SSL for both the server listener and REST API client connections for encrypted transport.

Tabs Reference

The runtime simulator screen exposes a different subset of tabs depending on the gateway type.