iso8583sim
Reference

Core API Reference

Parsing, building, validating, and the core data types. Generated from the package docstrings.

iso8583sim.core.types

class ISO8583Version

ISO 8583 protocol versions

  • ISO8583Version.V1987 = '1987'
  • ISO8583Version.V1993 = '1993'
  • ISO8583Version.V2003 = '2003'

class FieldType

Field data types in ISO 8583

  • FieldType.NUMERIC = 'n'
  • FieldType.ALPHA = 'a'
  • FieldType.ALPHANUMERIC = 'an'
  • FieldType.BINARY = 'b'
  • FieldType.SPECIAL = 's'
  • FieldType.TRACK2 = 'z'
  • FieldType.LLVAR = 'll'
  • FieldType.LLLVAR = 'lll'

class CardNetwork

Card network identifiers

  • CardNetwork.VISA = 'VISA'
  • CardNetwork.MASTERCARD = 'MASTERCARD'
  • CardNetwork.AMEX = 'AMEX'
  • CardNetwork.DISCOVER = 'DISCOVER'
  • CardNetwork.JCB = 'JCB'
  • CardNetwork.UNIONPAY = 'UNIONPAY'

class MessageClass

Message class identifiers (position 2 of MTI)

  • MessageClass.AUTHORIZATION = '1'
  • MessageClass.FINANCIAL = '2'
  • MessageClass.FILE_ACTIONS = '3'
  • MessageClass.REVERSAL = '4'
  • MessageClass.RECONCILIATION = '5'
  • MessageClass.ADMINISTRATIVE = '6'
  • MessageClass.FEE_COLLECTION = '7'
  • MessageClass.NETWORK_MANAGEMENT = '8'

class MessageFunction

Message function identifiers (position 3 of MTI)

  • MessageFunction.REQUEST = '0'
  • MessageFunction.RESPONSE = '1'
  • MessageFunction.ADVICE = '2'
  • MessageFunction.ADVICE_RESPONSE = '3'
  • MessageFunction.NOTIFICATION = '4'
  • MessageFunction.NETWORK_REQUEST = '8'
  • MessageFunction.NETWORK_RESPONSE = '9'

class MessageOrigin

Message origin identifiers (position 4 of MTI)

  • MessageOrigin.ACQUIRER = '0'
  • MessageOrigin.ACQUIRER_REPEAT = '1'
  • MessageOrigin.ISSUER = '2'
  • MessageOrigin.ISSUER_REPEAT = '3'
  • MessageOrigin.OTHER = '4'
  • MessageOrigin.OTHER_REPEAT = '5'

class FieldDefinition

Definition of an ISO 8583 field

FieldDefinition(field_type: iso8583sim.core.types.FieldType, max_length: int, description: str, field_number: int | None = None, encoding: str = 'ascii', min_length: int | None = None, padding_char: str | None = None, padding_direction: str = 'left') -> None

class ISO8583Message

Represents a complete ISO 8583 message

ISO8583Message(mti: str, fields: dict[int, str], version: iso8583sim.core.types.ISO8583Version = <ISO8583Version.V1987: '1987'>, network: iso8583sim.core.types.CardNetwork | None = None, raw_message: str | None = None, bitmap: str | None = None) -> None

message_class (property)

Get message class from MTI

message_function (property)

Get message function from MTI

message_origin (property)

Get message origin from MTI

class ISO8583Error

Base exception for ISO 8583 errors

class ParseError

Raised when parsing fails

class ValidationError

Raised when validation fails

class BuildError

Raised when message building fails

Functions

is_valid_mti(mti: str) -> bool

Check if MTI is valid.

Args: mti: Message Type Indicator string

Returns: bool: True if MTI is valid, False otherwise

Validates:

  • Length is 4 digits
  • All characters are numeric
  • Each position contains valid values

get_network_required_fields(network: iso8583sim.core.types.CardNetwork) -> list[int]

Get list of required fields for a specific network.

Args: network: Card network

Returns: List of required field numbers

get_field_format_pattern(network: iso8583sim.core.types.CardNetwork, field_number: int) -> str | None

Get network-specific field format pattern.

Args: network: Card network field_number: Field number

Returns: Regex pattern string if exists, None otherwise

is_binary_field(field_def: iso8583sim.core.types.FieldDefinition) -> bool

Check if field is binary type.

Args: field_def: Field definition

Returns: bool: True if field is binary, False otherwise

iso8583sim.core.parser

class EMVTag

EMV Tag data structure

EMVTag(tag: 'str', length: 'int', value: 'str', raw: 'str') -> None

class ISO8583Parser

Parser for ISO 8583 messages with network support

ISO8583Parser(version: 'ISO8583Version' = <ISO8583Version.V1987: '1987'>, pool: 'MessagePool | None' = None)

parse(message: 'str', network: 'CardNetwork | None' = None) -> 'ISO8583Message'

Parse an ISO 8583 message string into an ISO8583Message object

parse_file(filename: 'str') -> 'list[ISO8583Message]'

Parse multiple messages from file

iso8583sim.core.builder

class ISO8583Builder

Builder for creating ISO 8583 messages with network support

ISO8583Builder(version: iso8583sim.core.types.ISO8583Version = <ISO8583Version.V1987: '1987'>)

build(message: iso8583sim.core.types.ISO8583Message) -> str

Build raw ISO 8583 message string from message object

build_emv_data(emv_tags: dict[str, str]) -> str

Build EMV data field (field 55) from tags

create_message(mti: str, fields: dict[int, str]) -> iso8583sim.core.types.ISO8583Message

Create an ISO8583Message object with validation

create_network_management_message(message_type: str, network: iso8583sim.core.types.CardNetwork | None = None) -> iso8583sim.core.types.ISO8583Message

Create a network management message

create_response(request: iso8583sim.core.types.ISO8583Message, response_fields: dict[int, str]) -> iso8583sim.core.types.ISO8583Message

Create a response message based on a request message

create_reversal(original: iso8583sim.core.types.ISO8583Message, additional_fields: dict[int, str] | None = None) -> iso8583sim.core.types.ISO8583Message

Create a reversal message

iso8583sim.core.validator

class ISO8583Validator

Enhanced validator for ISO 8583 messages with network support

ISO8583Validator()

validate_bitmap(bitmap: str) -> tuple[bool, str | None]

Validate bitmap format and content

Args: bitmap: Hexadecimal bitmap string

Returns: (is_valid, error_message)

validate_emv_data(emv_data: str) -> list[str]

Validate EMV data format (TLV structure)

validate_field(field_number: int, value: str, field_def: iso8583sim.core.types.FieldDefinition, network: iso8583sim.core.types.CardNetwork | None = None) -> tuple[bool, str | None]

Validate field value

validate_field_compatibility(field_number: int, value: str, version: iso8583sim.core.types.ISO8583Version) -> list[str]

Validate field compatibility with ISO version

Args: field_number: Field number to validate value: Field value version: ISO8583 version

Returns: List of compatibility errors

validate_message(message: iso8583sim.core.types.ISO8583Message) -> list[str]

Validate complete ISO 8583 message

validate_mti(mti: str) -> tuple[bool, str | None]

Validate Message Type Indicator

Args: mti: 4-digit MTI string

Returns: (is_valid, error_message)

validate_network_compliance(message: iso8583sim.core.types.ISO8583Message) -> list[str]

Validate network-specific requirements

validate_pan(pan: str) -> bool

Validate Primary Account Number using Luhn algorithm

Args: pan: Card number string

Returns: True if valid, False otherwise

validate_processing_code(code: str) -> bool

Validate processing code format

iso8583sim.core.emv

EMV (Europay, Mastercard, Visa) TLV data handling.

This module provides functions for parsing and building EMV Tag-Length-Value encoded data, commonly found in ISO 8583 Field 55.

Functions

parse_emv_data(data: 'str') -> 'dict[str, str]'

Parse EMV TLV data into a dictionary of tags and values.

Args: data: Hex-encoded EMV TLV data

Returns: Dictionary mapping tag strings to value strings (hex-encoded)

Raises: ValueError: If data is malformed

build_emv_data(tags: 'dict[str, str]') -> 'str'

Build EMV TLV data from a dictionary of tags and values.

Args: tags: Dictionary mapping tag strings to value strings (hex-encoded)

Returns: Hex-encoded EMV TLV data string

get_tag_name(tag: 'str') -> 'str'

Get the description of an EMV tag.

Args: tag: Tag identifier (hex string)

Returns: Description of the tag, or “Unknown” if not found

explain_tvr(tvr_hex: 'str') -> 'list[str]'

Explain Terminal Verification Results.

Args: tvr_hex: 5-byte TVR as hex string (10 characters)

Returns: List of issues/flags that are set

explain_cid(cid_hex: 'str') -> 'str'

Explain Cryptogram Information Data.

Args: cid_hex: CID byte as hex string

Returns: Description of the cryptogram type

iso8583sim.core.pool

Object pooling for high-throughput ISO8583 message processing.

class MessagePool

Thread-safe object pool for ISO8583Message instances.

Using a pool reduces object allocation overhead in high-throughput scenarios by reusing message objects instead of creating new ones.

Usage: pool = MessagePool(size=100)

# Get a message from the pool
msg = pool.acquire("0100", {2: "4111111111111111"})

# Process the message...

# Return it to the pool when done
pool.release(msg)

Note: Messages returned to the pool have their fields cleared, so don’t hold references to field data after releasing.

MessagePool(size: int = 100)

acquire(mti: str, fields: dict[int, str], version: iso8583sim.core.types.ISO8583Version = <ISO8583Version.V1987: '1987'>, network: iso8583sim.core.types.CardNetwork | None = None, raw_message: str | None = None, bitmap: str | None = None) -> iso8583sim.core.types.ISO8583Message

Get a message from the pool or create a new one.

Args: mti: Message Type Indicator fields: Message fields dictionary version: ISO8583 version network: Card network raw_message: Original raw message string bitmap: Message bitmap

Returns: An ISO8583Message instance (either recycled or new)

clear() -> None

Clear all messages from the pool.

max_size (property)

Get maximum pool size.

release(msg: iso8583sim.core.types.ISO8583Message) -> None

Return a message to the pool for reuse.

Args: msg: The message to return to the pool

Note: The message’s fields are cleared to avoid holding references to old data.

size (property)

Get current number of messages in the pool.

Functions

get_default_pool(size: int = 100) -> iso8583sim.core.pool.MessagePool

Get or create the default global message pool.

Args: size: Pool size (only used on first call)

Returns: The default MessagePool instance

reset_default_pool() -> None

Reset the default global pool.