pyiso8583

4.0.1 · active · verified Thu Apr 16

pyiso8583 is a Python package designed for serializing and deserializing ISO8583 data. It converts raw ISO8583 byte streams into Python dictionaries and vice-versa, supporting various custom specifications for field lengths, data encoding (like BCD, ASCII, EBCDIC), and field types (fixed, LLVAR, LLLVAR). The current version is 4.0.1, with releases typically occurring a few times a year, indicating active development.

Common errors

```
iso8583.decoder.DecodeError: Message is too short: field <FIELD_NUMBER> pos <POSITION>
```
cause The raw ISO8583 message bytearray is shorter than expected based on the provided specification, or a field's declared length exceeds the remaining message bytes.

fix Verify the integrity of the incoming raw ISO8583 message. Check your `spec` dictionary, particularly the `max_len` and `len_type` properties for the reported field, to ensure they correctly match the message format.
```
iso8583.encoder.EncodeError: Data length for field <FIELD_NUMBER> is <ACTUAL_LENGTH>, expected <EXPECTED_LENGTH>
```
cause The data provided in the Python dictionary for a specific ISO8583 field does not match the length or format expected by the field's definition in the specification.

fix Review the data being assigned to the field in your Python dictionary (`doc_dec`) and compare it against the `max_len`, `len_type`, and `data_enc` defined for that field in your `spec` dictionary. Adjust the data or the specification to ensure they are compatible.
```
TypeError: Decoded ISO8583 data must be dict, not <TYPE>
```
cause The `doc_dec` argument passed to `iso8583.encode()` was not a Python dictionary.

fix Ensure that the first argument to `iso8583.encode()` is always a dictionary containing the ISO8583 field data.
```
TypeError: Encoded ISO8583 data must be bytes or bytearray, not <TYPE>
```
cause The `s` argument passed to `iso8583.decode()` was not a bytes or bytearray instance.

fix Ensure that the first argument to `iso8583.decode()` is always a `bytes` or `bytearray` object representing the raw ISO8583 message.

Warnings

breaking Upgrading from `pyiso8583` v3.x.x to v4.x.x may introduce breaking changes. Always review the 'Change Log' in the official documentation before upgrading major versions to understand API modifications, especially around specification structures or function signatures.
Fix: Consult the official 'Change Log' on Read the Docs for specific migration steps. Test your application thoroughly after upgrading.
gotcha Incorrect or incomplete ISO8583 specifications are a common source of encoding/decoding errors. Ensure your custom specifications accurately define field lengths, data encoding, and types for all expected fields, including proper handling of binary or BCD data padding.
Fix: Refer to the 'Specifications' section in the documentation (iso8583.specs module) for detailed guidance on creating and validating custom specifications. Pay close attention to `len_count`, `data_enc`, `left_pad`, and `right_pad` for complex field types.
gotcha Handling odd-length binary or BCD fields requires specific padding configuration within the field specification (e.g., `left_pad` or `right_pad`). Failure to specify this can lead to incorrect message parsing or generation.
Fix: When defining fields with `data_enc` set to 'b' (binary/BCD) and `len_count` set to 'nibbles', ensure you explicitly define either `left_pad` or `right_pad` with the appropriate padding digit (0-F).

Install

pip install pyiso8583 Install with pip

Imports

iso8583
```
import iso8583
```

default_ascii

from iso8583.specs import default_ascii as spec

DecodeError
```
from iso8583.decoder import DecodeError
```
EncodeError
```
from iso8583.encoder import EncodeError
```

Quickstart

This quickstart demonstrates how to decode a raw ISO8583 message using the default_ascii specification, modify some fields, and then encode it back into a raw bytearray. It uses `iso8583.decode` and `iso8583.encode` functions.

import iso8583
from iso8583.specs import default_ascii as spec
import pprint

# Example ISO8583 raw message (MTI '0200', Field 2 '1234567890', Field 12 '123456')
encoded_raw_message = b'02004000000000000000101234567890123456'

# Decode the message
decoded_data, encoded_fields_info = iso8583.decode(encoded_raw_message, spec)
print("Decoded data:")
pprint.pprint(decoded_data)

# Modify the decoded message for a response (e.g., '0210' response, add field 39)
decoded_data['t'] = '0210'
decoded_data['39'] = '00'

# Encode the modified message back to raw bytes
response_raw_message, response_encoded_fields_info = iso8583.encode(decoded_data, spec)
print("\nEncoded response raw message:")
print(response_raw_message)
print("\nEncoded response fields info:")
pprint.pprint(response_encoded_fields_info)

view raw JSON →