FlexSim
ISO 8583 Simulator Manual

Part IGetting started

What the application is for, what it is made of, and how to get a message onto the wire in five minutes.

1What FlexSim is

FlexSim is a desktop simulator for ISO 8583, the message format card payment switches speak. You use it to build a message by hand, send it to a host over TCP, and read back exactly what came out — byte by byte, and field by field.

It is built for the two jobs that come up constantly in payment integration work:

• Acting as a terminal or acquirer. You compose a request — a purchase, a balance enquiry, a network sign-on — and send it to the switch you are testing against. FlexSim shows you the bytes it sent and parses the reply.
• Acting as the host. You define what the reply should look like, and FlexSim listens on a port and answers requests as they arrive. This lets you test the other side's terminal or acquirer without a real issuer behind it.

Around those two jobs it carries the machinery that payment testing actually needs: per-switch message definitions, encrypted card and key storage, EMV cryptogram generation (ARQC and ARPC), PIN block and CVV/PVV calculation, DUKPT key derivation, and a TLV decoder.

2The pieces, and how they fit together

Six things make up everything you will do in FlexSim. Getting these straight now saves a lot of confusion later.

The chain runs: a test case lives in a suite, which belongs to a spec profile. The test case may be linked to a card profile, which references keys. Sending it uses the connection.

3Installing and starting the application

3.1  What you get

FlexSim is portable. There is no installer, no registry use, and nothing to uninstall. On Windows and Linux the package contains just two items:

FlexSim.exe                 the whole application
Assets\simulator.db         the first-run template database

Unpack the archive anywhere you can write to and run FlexSim.exe. On Linux and macOS the download is a .tar.gz rather than a zip, because a zip cannot record the executable bit.

3.2  Where your data is kept

Your work — cards, keys, suites, test cases, settings and the message log — is never stored next to the program. It lives in one fixed place per user:

On the very first run the bundled template is copied there. After that the template is never used for your data again, so you can delete, move or replace the program folder and keep everything.

3.3  Choosing the active spec profile

Every launch begins by asking which spec profile to use. Nothing else opens until you answer, because the profile decides how every message is built and read.

Four profiles ship with the application:

You are not locked in: the active profile can be changed at any time from the status bar without restarting — see section 8.

3.4  The main window

4Five-minute tour: send your first message

This walkthrough gets one message out and one reply back. It uses the test cases that come with the application, so nothing needs building first. You will need something listening on a TCP port — a real test host, or any simple echo server on your own machine.

1. Start FlexSim and pick a profile. Choose the one that matches the host you are testing against, and press Select.
2. Set up the connection. Press Connection on the toolbar. Choose Client (connect to a server), type the host and port, and press Save. Close the window.
3. Connect. Press Connect. The status light at the bottom-left turns green and reads Connected.
4. Pick a test case. In the tree on the left, click a suite to open it, then click a test case. It highlights, and Send Message becomes available.
5. Send. Press Send Message — or Ctrl+Enter. The live log shows the bytes that went out, the field-by-field breakdown of the request, and then the reply.

Part IIThe main window

Everything on the one screen you will spend most of your time in.

5The toolbar

The toolbar is in two halves. On the left are the things you do to run a message; on the right are the things you set up beforehand.

5.1  Running a message (left group)

5.2  Setting things up (right group)

6The test suite tree

The left-hand panel lists the suites belonging to the active spec profile, and the test cases inside each one. Its three gestures are printed under the heading:

• Click a suite to open or close it; click a test case to select it. Selecting is what enables Send Message.
• Double-click a test case to open it in the test case editor.
• Right-click a suite — or the Test Suites heading — for the suite menu.

Each test case row carries small markers summarising what it does — whether it sends or answers, and whether its reply is checked. Hovering a row spells the same thing out in words.

7The live log

The dark panel on the right is a running commentary on everything the application does: connection state changes, each message sent and received, and any warning about why a value could not be produced.

Two controls sit above it:

Everything shown here is also written to a log file on disk, unless you turn that off in Settings. The on-screen log is never trimmed automatically.

8The status bar and the active profile

The bar along the bottom shows four things: the connection state and its indicator light, the active spec profile, the version you are running, and the author.

The profile name is a button. Pressing it reopens the picker, so you can change the active spec profile without restarting.

Part IIISetting up

The connection, the keys, the cards and the message definitions — the material every test case is built from.

9Connection

Connection on the toolbar opens the transport settings. There is one connection record, shared by everything.

Press Save to store the settings. Changes take effect the next time you press Connect.

10Keys

Key material is held in one shared store and referenced by name. A key is entered once and any number of card profiles can point at it, so rotating a key is one edit rather than one per card.

10.1  Adding a key

1. Press New.
2. Choose the Key Type. This is what decides which dropdown on the card screen will offer it.
3. Give it a Description. This is the name you will pick it by, so make it say which host and which environment it belongs to.
4. Type the Key Value as hex — 32 hex characters for a double-length key, 48 for triple-length.
5. Check the KCV shown live under the value box against the one your key custodian gave you, then press Save.

11Card profiles

Card Data holds the cards your test cases draw values from. Pick a card in the list on the left and its details fill the panel on the right.

11.1  Card Data

11.2  Security Data and Auto Calculate

The Security Data group holds CVV, CVV2, iCVV, PIN block and PVV. You can type them, or press Auto Calculate to derive them from the card values and the selected keys.

• CVV, CVV2, iCVV need the PAN, expiry, service code and a CVK. The iCVV is the chip variant — the same calculation with the service code replaced.
• PVV needs the PAN, the PIN, the PVKI and a PVK. If either the PIN or the key is missing, FlexSim says which rather than leaving the box empty, and it shows the TSP it used underneath so you can check the input.
• PIN block needs the PIN and the PAN, and a ZPK if you want it encrypted.

11.3  Keys

These are references, not copies. Change a key's value in the key manager and every card pointing at it follows.

12Track 2

Compose… next to the Track 2 box builds the track from the values already on the card, and lets you decide what goes in it and in what order.

• The separator is typed, not chosen from a list. = and D are one-click buttons because they are the usual two, but any character can go in the row.
• Switching a segment off leaves it out but keeps its place in the order, so switching it back on puts it where it was.
• Deviating from ISO/IEC 7813 — a different order, more than 37 characters, non-digits — is reported but never blocked. Sending a malformed track is a legitimate test.
• Only Apply writes the result into the card's Track 2 box, so a track you typed by hand is never overwritten silently.

13Spec profiles

A spec profile is the application's description of one switch's message format. It is not your data — it is a statement of how that switch expects messages to look — and it governs both how FlexSim builds a message and how it reads one back.

Spec Profiles on the toolbar opens the editor. The list on the left holds every profile; the panel on the right holds the one you have selected, in three collapsible sections.

13.1  Basic Information

13.2  Headers

Application headers that go in front of the MTI — the NPS profile has six of them, Arksys has none. Each row is a name, an encoding and a length.

13.3  Fields

The Fields section is the bulk of a profile — one row per data element. Because a profile can hold 130 of them, two things make it workable: the filter box, and collapsing the sections above so the grid gets the whole panel.

13.4  What happens to profiles when you upgrade

Installing a newer version of FlexSim does not touch your cards, keys, suites or test cases — but it does reconcile the shipped spec profiles, because a fix to a profile is a fix to the product. On the first start of a new version:

A refreshed profile keeps its identity, so every suite, test case and log row that pointed at it still does. Renaming is never done either: a profile you know as EBC stays called EBC even though newer installations call the same profile 123.

14Subfields and composition

Some data elements are not a single value but a structure: DE-55 is a string of BER-TLV tags, DE-57 in the NPS profile is a counted token buffer, DE-106 is a nested TLV tree. In FlexSim these are described as subfields, and the field's value is composed from them.

Select a field in the spec editor and press Edit Subfields.

14.1  Composition

The Composition dropdown at the top says how the children are turned into the parent's value. It is declared, never guessed from the field number.

14.2  Roles

A child's Role says what it contributes. This is what keeps the framing declarative — nothing is hardcoded against a particular data element.

14.3  Nesting

Subfields nest to any depth. A subfield that has children is a container: its value is composed from what it holds and cannot be typed directly. The grid shows the tree flattened and indented, and every row has its own Add child button.

Composition inherits: a child left on Auto takes NestedTlv under a NestedTlv parent, and Fixed under a TokenBuffer — so a profile declares it once at the top rather than on every element.

Part IVBuilding test cases

A test case is one message. This part covers where it lives, how each field gets its value, and how to say what a good reply looks like.

15Test suites

A suite is a named folder of test cases belonging to one spec profile. Right-click in the tree and choose Add Test Suite.

Suites are worth organising by intention rather than by message type — Network, Authorization, Financial, Reversals, Negative cases. Order matters in one specific place: when a suite is used as a set of responder rules, the rules are tried in the order the test cases sit in (section 23).

16The test case editor

Double-click a test case in the tree to open it, or press New Test for an empty one.

16.1  The header

16.2  The field grid

Above the grid, the search box filters by field number or name, and Select All / Deselect All tick and untick everything. Filtering only changes what is shown — it never changes what is ticked.

16.3  The footer

17How a field gets its value

The GenerateMethod on each row decides where the value comes from when the message is built. This is the single most important idea in the editor: a value typed into a row is only used if the method says to use it.

17.1  What Auto produces

17.2  Placeholders

Any value can contain placeholders, substituted when the message is built. They work with Static, so you can mix fixed text and generated parts.

18Editing subfield values

A field with subfields shows its composed value in the grid and cannot be typed into. Press Edit… in its Subfields column to open the values window.

• Enable decides whether a tag is included. An unticked or empty tag is skipped entirely rather than sent as an empty TLV.
• GenerateMethod works per subfield exactly as it does per field — so tag 9F26 can be Auto while the rest are Static.
• Clear values empties every subfield of this field.
• Cancel restores the values as they were when the window opened; Done keeps them.

19Importing a captured message

Instead of ticking fields one at a time, you can paste a message captured from the wire and let FlexSim take it apart. Import from Hex is available on the request, response and reversal screens.

The message is parsed with the active spec profile, and the import then:

• resets everything first, so what ends up ticked is exactly the message's bitmap;
• fills the MTI box and every data element the message carried;
• takes composite fields apart into their subfields, matching TLV tags recursively;
• matches headers by name;
• reports anything it could not read back.

20Expected response rules

Expected… defines what a good reply looks like. Every rule must hold for the case to pass.

The Note column is free text and appears in the result, so it is worth saying why the rule exists rather than restating it.

Part VRunning messages

Getting a message onto the wire, reading what came back, and answering requests instead of sending them.

21Connecting and sending

21.1  Connect

Press Connect. In client mode FlexSim dials the host and port from the Connection window; in server mode it starts listening. The status bar reports the result.

21.2  Send

Select a test case in the tree and press Send Message, or Ctrl+Enter. What happens next, in order:

1. Every enabled field is resolved — static values taken as they are, Auto fields generated, Card Data fields read from the linked card, placeholders substituted.
2. Composite fields are composed from their subfields, with cryptograms computed at this point.
3. If the message carries DE-55, the CVV inside track 2 is swapped for the card's iCVV.
4. The message is encoded per the active spec profile, framed with its two-byte length header and written to the socket.
5. FlexSim waits for the reply, parses it with the same profile, and logs both.
6. If the case has a reversal defined, the reversal is sent after its delay.

Set Iterations above 1 to repeat. Each send waits for its reply before the next one goes out, and a timeout stops the run. Stop ends it after the message currently in flight.

21.3  Reading the live log

Each message in the log is written as a block: a heading line giving direction, MTI and byte count, then the hex, then the ASCII rendering, then — with Parsed detail on — every data element it carried. EMV tags inside DE-55 are listed with their tag numbers and names, indented under the field.

Warnings appear inline in the same stream, which is where to look when a field is missing from a message you expected it in. Typical lines say that an ARQC was requested with no card linked, that a Copy field had no source picked, or that a track could not be recomposed.

22Reading the message log

The live log is cleared whenever you press Clear or restart. The message log is the permanent record, kept in the database per spec profile.

Refresh re-reads the list; Clear Log empties it for the current profile. The heading counts what is there.

23Answering requests — responder mode

A test case can answer requests instead of sending one. This turns FlexSim into a small host: the other side sends you a 0200, and you reply with the 0210 you defined.

23.1  Defining the reply

Open a test case and press Response….

23.2  Arming and answering

Select a responder test case in the tree. Send Message is retitled Listen for Request, and Iterations becomes how many requests to answer before disarming.

23.3  A suite as a set of rules

Arming does not load just the one test case — it loads every responder case in that suite as a rule, in the order they sit in. So a suite becomes a small host that answers different requests differently.

• A rule matches when its MTI agrees and every field it fills in agrees. A blank MTI is a catch-all, and an enabled field left empty means "any value".
• The first match in order wins — not the most specific one. Reorder the suite and you know exactly what changes.
• If nothing matches, the case you actually armed answers, and the log says why every rule was passed over. Going silent would be worse than answering.
• The request definition on a responder case is treated as an expectation: every field that differs from what arrived is logged. This is diagnostic, not gating — the reply is sent either way.

23.4  ARPC — answering the card's cryptogram

A response field with subfields is composed properly, so a reply can carry real BER-TLV in DE-55. Inside it, tag 91 set to Auto is filled with the issuer authentication data.

• The session key is derived from the incoming request's tags along the same AC key → card key → session key chain, which means computing the ARPC also verifies the card's 9F26. The result is logged either way.
• The ARC is the ASCII of the reply's own DE-39, so "00" becomes 3030. A literal four-hex value entered instead is passed straight through, for a spec that really uses BCD.
• Method 1 produces ARPC(8) ‖ ARC(2) and needs no CSU. Method 2 produces ARPC(4) ‖ CSU(4), has no ARC of its own, and fails loudly rather than guessing if the card has no CSU.
• No card, no AC key, or no DE-55 in the request means no tag 91 and a logged reason — never a silently empty 91.

24Reversals

A test case can send a reversal automatically once its request has been answered. Press Reversal… in the test case editor.

24.1  Echo and Copy

Two generation methods exist for reversals specifically:

• Echo from request copies the same field number out of the original request. Most of a reversal is this.
• Copy from request field copies a different field number. This is what an original-data element is: DE-90 carries the original MTI, trace number, date and acquirer, each taken from a different field of the transaction being reversed. Picking Copy opens a submenu of the data elements the request actually sends, including edits you have not saved yet.

Subfields copy too, which is what a positional original-data element really needs. The Copy entry appears on a subfield only when the reversal editor opened the values window; it is never offered on a container, whose value is composed rather than set.

Part VITools and settings

The calculators that save a trip to a separate utility, and the preferences that change how the application looks and what it keeps.

25Reference & Tools

Tools on the toolbar opens a set of lookups and calculators in four tabs. Nothing here reads or writes the database — it is all scratch work.

25.1  Card values

Everything the Card Data screen calculates, without needing a saved card. Keys are typed in rather than picked from the key store, which keeps the tab a pure lookup.

Each result names what it still needs until it has it — needs PAN, expiry, service code, CVK — so nothing is silently blank.

25.2  Converter

Paste hex, ASCII text, or EBCDIC hex; every reading is shown at once, so you do not have to say which one you meant.

25.3  Keys

Four key utilities on one tab.

25.4  TLV decoder

Paste a field value as hex and get the BER-TLV structure back, tag by tag, with the EMV tag names filled in.

26Settings

26.1  Appearance

Follow system, Light or Dark. The change reaches every open window immediately — no restart.

26.2  Log files

Changing the folder affects new files only — files already written stay where they are. A stored folder that has gone missing or become unwritable falls back to the default at startup.

26.3  Log colours

The background and text colour of the live log panel, with a preview and a contrast reading. These are yours to set and are not part of the light/dark theme.

27Protecting the database with a master password

Card data and key material are always encrypted at rest. By default the encryption key is derived from a passphrase built into the application, which means anyone with a copy of the program and your database file can read them.

Setting a master password replaces that with a key derived from your passphrase and a random salt.

With a master password set, FlexSim opens to an unlock prompt instead of the main window. Card data and keys stay encrypted until it is entered.

Part VIIWorked examples

Four end-to-end tasks, each one a thing people actually sit down to do.

28Example 1 — A purchase with chip data

Goal. Build a 0200 purchase for a chip card, with DE-55 carrying a real ARQC, and send it.

Set up the card and its key

1. Open Manage Keys, press New, choose type AC, describe it (AC – UAT issuer), paste the 32-hex master key and check the KCV against what the issuer gave you. Save.
2. Open Card Data, press New and fill in the PAN, expiry, service code and card sequence number. The sequence number matters — it goes into the card key derivation, and a wrong one produces a cryptogram the issuer rejects with no useful error.
3. Pick your new key in the AC dropdown. Set ARPC Method to match the issuer.
4. Press Compose… beside Track 2, check the segments and order, and press Apply. Then press Auto Calculate to fill the security values. Save.

Build the test case

1. Right-click in the tree, Add Test Suite, name it Authorization and pick your spec profile.
2. Press New Test. Name it Chip purchase, choose the suite, and choose your card in Card Data.
3. Set the MTI to 0200 and tick the fields the switch expects. A typical minimum:
   • DE-2 — method Card Data
   • DE-3 — 000000, Static
   • DE-4 — the amount, Static, e.g. 000000010000
   • DE-7, DE-12, DE-13 — Auto (current date and time)
   • DE-11 — Auto, or Static {{STAN}}
   • DE-14 — Card Data
   • DE-22 — 051 (chip read), Static
   • DE-35 — Card Data
   • DE-41, DE-42, DE-43 — your terminal and merchant, Static
   • DE-49 — the currency, Static
   • DE-55 — ticked; its value comes from its subfields
4. On the DE-55 row press Edit…. Tick the tags the switch requires and give each a value, then set:
   • 9F26 to Auto — the ARQC
   • 9F36 to Auto — the ATC, stepped each send
   • 9A and 9C to Auto
   • 9F02 to Auto — it mirrors DE-4
   Watch the composed value at the top of the window grow as you go. Press Done.
5. Press Expected…, then Approved (DE-39 = 00), then Apply.
6. Save Changes.

Send it

1. Connection → client, host, port, Save.
2. Connect.
3. Click the test case in the tree and press Send Message.
4. Read the parsed breakdown in the live log. Check that DE-55 lists the tags you expect and that 9F26 is not empty — if it is, the log line just above says why.

29Example 2 — Acting as the issuer host

Goal. Let someone else's terminal send you authorizations, and answer them — approving most, declining one card.

1. Connection → Server (listen for connections), set the port, Save.
2. Make a suite called Issuer. The order of cases in it is the order the rules are tried, so put the specific ones first.
3. First case — the declined card. Create a test case, tick DE-2 and give it the PAN you want declined. This is the match condition, not something that gets sent. Then press Response…:
   • tick Response active
   • leave Response MTI blank so it derives 0210 from the 0200
   • press Echo all enabled to mirror the request back
   • tick DE-39 as Send with value 05
   Apply, then save the case.
4. Second case — approve everything else. Another test case, no fields ticked and a blank MTI, so it is a catch-all. Its response echoes the request and sends DE-39 = 00. If you are answering chip transactions, tick DE-55 in the response and set tag 91 to Auto, then link the case to the card so the AC key is available.
5. Press Connect, select either responder case in the tree, set Iterations to the number of requests you want to answer, and press Listen for Request.
6. Watch the log. For each request it names the rule that matched, or lists why each was passed over, and reports every field of the request that differed from the case's own definition.
7. Stop disarms.

30Example 3 — A reversal after the reply

Goal. Send the purchase from Example 1, then reverse it automatically.

1. Open the Chip purchase case and press Reversal….
2. Tick Reversal active. Set Reversal MTI to 0400 and Delay to a few seconds if you want to see the two messages apart in the log.
3. Tick the fields the reversal carries, then press Echo all enabled — most of a reversal is the original request repeated.
4. For the original-data element (often DE-90), set it to Copy from request field and pick the source data element from the submenu. Do the same for its subfields if it is positional: open its Edit… window and set each child's source.
5. Check the status line at the bottom of the reversal editor. It counts the fields that are on Copy with no source picked — those will be left out.
6. Apply, save, and send the test case as usual. The log shows the request, the reply, the delay, then the reversal.

31Example 4 — Working out a PVV by hand

Goal. Check a PVV the host produced, without touching your saved cards.

1. Tools → Card values.
2. Type the PAN, the PIN and the PVKI.
3. Paste the PVK into the PVK box.
4. Read the PVV under Calculated.
5. If it does not match the host, compare the PVV input (TSP) line underneath against what the host says it used. The TSP is the 11 rightmost PAN digits excluding the check digit, then the PVKI, then the first four PIN digits — and a disagreement is almost always in that construction rather than in the cipher.

AppendicesReference

Lookup tables, file locations, troubleshooting, and what this version cannot do.

Appendix A — Generation methods

A value that cannot be produced is omitted and logged, never sent empty. Auto and Card Data on a container subfield do nothing — a container's value is composed from its children.

Appendix B — Subfield composition and roles

Inheritance. A child left on Auto takes NestedTlv under NestedTlv and Fixed under TokenBuffer.

Appendix C — Placeholders

The {{CARD.*}} placeholders only substitute when the test case has a card linked; otherwise they are left in place, which makes the omission visible in the log rather than silent.

Appendix D — Files, folders and backups

The first two lines of the log at every start are the two facts any support conversation needs: the version, and the database path.

[2026-09-12 09:12:18] [Information] → FlexSim 1.0.3
[2026-09-12 09:12:18] [Information] → Database: C:\Users\you\AppData\Local\FlexSim\simulator.db

Backing up

1. Close FlexSim. The database uses a write-ahead log, so copying it while the application is running can leave the most recent changes behind.
2. Copy simulator.db. If simulator.db-wal is present and non-empty, copy that too.

To move your work to another machine, install FlexSim there, run it once so the folder exists, close it, and drop your simulator.db over the one it made.

Appendix E — Troubleshooting

Appendix F — Known limitations in 1.0.3

These are things the interface appears to offer that this version does not yet do. They are listed so that time is not lost looking for a fault that is not there.

Appendix G — Glossary

FlexSim 1.0.3 — User Manual · 12 September 2026 · Developed by Ahmed Telleb