ISO8583 Protocol Serializer & Deserializer¶

iso8583 – Readme¶

iso8583¶

iso8583 package serializes and deserializes ISO8583 data between a bytes or bytearray instance containing ISO8583 data and a Python dict.

iso8583 package supports custom specifications that can define

Field length and data encoding, such as BCD, ASCII, EBCDIC, etc.

Field type, such as fixed, LLVAR, LLLVAR, etc.

Maximum length

Optional field description

Multiple specifications can co-exist to support ISO8583 messages for POS, ATM, file actions, and so on. Simply define a new specification dictionary. iso8583 package includes a starter specification in iso8583.specs module that can be used as a base to create own custom/proprietary specifications.

Additional information is available on RTD.

Install:

pip install pyiso8583

Encoding & Decoding¶

Decode raw iso8583 message using iso8583.decode. It returns two dictionaries: one with decoded data and one with encoded data.

>>> import pprint
>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b'02004000000000000000101234567890'
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> pprint.pp(doc_dec) # Decoded data
{'bm': {2}, 't': '0200', 'p': '4000000000000000', '2': '1234567890'}
>>> pprint.pp(doc_enc) # Broken down encoded data
{'bm': {2},
 't': {'len': b'', 'data': b'0200'},
 'p': {'len': b'', 'data': b'4000000000000000'},
 '2': {'len': b'10', 'data': b'1234567890'}}

Modify the decoded message to send a response back. Change message type from ‘0200’ to ‘0210’. Remove field 2 (PAN). And add field 39 (Response Code).

>>> doc_dec['t'] = '0210'
>>> doc_dec['bm'].discard(2)
>>> doc_dec['bm'].add(39)
>>> doc_dec['39'] = '05'

Encode updated ISO8583 message using iso8583.encode. It returns a raw ISO8583 message and a dictionary with encoded data.

>>> s, doc_enc = iso8583.encode(doc_dec, spec)
>>> s
bytearray(b'0210000000000200000005')
>>> pprint.pp(doc_enc)
{'t': {'len': b'', 'data': b'0210'},
 'bm': {39},
 'p': {'len': b'', 'data': b'0000000002000000'},
 '39': {'len': b'', 'data': b'05'}}

Optional Helper Functions¶

Pretty print a decoded dictionary using iso8583.pp

Add/update fields in a decoded dictionary using iso8583.add_field

Remove fields in a decoded dictionary using iso8583.del_field

Contribute¶

iso8583 package is hosted on GitHub.

Feel free to fork and send contributions over.

iso8583 – How-To ¶

Table of Contents

iso8583 – How-To

Create Own/Proprietary Specifications ¶

iso8583 comes with specification sample in iso8583.specs.py. Feel free to copy sample specification dict and modify it to your needs. Refer to iso8583.specs for configuration details.

Create ISO8583 Message ¶

iso8583 converts a Python dict into a bytearray. A the minimum the dict must have

't' key containing message type, e.g. '0200'.
'bm' key containing fields numbers to be added to the message.
'1' .. '128' key with data for each field specified in 'bm' set.

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> doc_dec = {
...     't': '0200',
...     'bm': set([3]),
...     '3': '111111'}
>>> raw, doc_enc = iso8583.encode(doc_dec, spec)
>>> raw
bytearray(b'02002000000000000000111111')

Let’s add another field.

>>> doc_dec['bm'].add(12)
>>> doc_dec['12'] = '122530'
>>> raw, doc_enc = iso8583.encode(doc_dec, spec)
>>> raw
bytearray(b'02002010000000000000111111122530')

Add Secondary Bitmap ¶

You don’t need to explicitly add secondary bitmap. It’s auto generated when at least one 65-128 field is present.

>>> import pprint
>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> doc_dec = {
...     't': '0200',
...     'bm': set([102]),
...     '102': '111111'}
>>> raw, doc_enc = iso8583.encode(doc_dec, spec)
>>> raw
bytearray(b'02008000000000000000000000000400000006111111')
>>> pprint.pp(doc_enc)
{'t': {'len': b'', 'data': b'0200'},
 'bm': {1, 102},
 'p': {'len': b'', 'data': b'8000000000000000'},
 '1': {'len': b'', 'data': b'0000000004000000'},
 '102': {'len': b'06', 'data': b'111111'}}

Check for Mandatory Fields ¶

Many ISO8583 implementations need to check if all mandatory fields are received. It’s easy to do this using 'bm' set.issuperset().

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b'02004000000000000000101234567890'
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> doc_dec['bm']
{2}
>>> mandatory_fields = set([2,3])
>>> doc_dec['bm'].issuperset(mandatory_fields)
False
>>> mandatory_fields = set([2])
>>> doc_dec['bm'].issuperset(mandatory_fields)
True

Convert to JSON ¶

iso8583 output is almost JSON ready. All that’s required is to convert 'bm' from set to a list.

>>> import json
>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b'02004000000000000000101234567890'
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> doc_dec['bm'] = sorted(doc_dec['bm'])
>>> json.dumps(doc_dec)
'{"bm": [2], "t": "0200", "p": "4000000000000000", "2": "1234567890"}'

Convert from JSON ¶

Converting iso8583 output from JSON back to required dictionary is easy. All that’s required is to convert 'bm' back from list to a set.

>>> import json
>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> json_data = b'{"bm": [2], "t": "0200", "p": "4000000000000000", "2": "1234567890"}'
>>> doc_dec = json.loads(json_data)
>>> doc_dec['bm'] = set(doc_dec['bm'])
>>> raw, doc_enc = iso8583.encode(doc_dec, spec)
>>> raw
bytearray(b'02004000000000000000101234567890')

iso8583 – Specifications ¶

Table of Contents

iso8583 – Specifications

An ISO8583 spec is a Python dict instance. It describes how each field needs to be encoded or decoded.

Fields ¶

Supported fields:

h - Message Header. If a specification does not have a header then set max_len to 0 to disable it.
t - Message Type Identifier
p - Primary Bitmap
1 - Secondary Bitmap
2 .. 128 - Regular fields

Field Properties ¶

Each field defines these properties:

data_enc - field’s data encoding type, where:
- Use b for binary-coded decimal data (e.g. an ABCD hex string is encoded as \xAB\xCD 2-byte value).
- Otherwise, provide any valid Python encoding. For example, ascii or latin-1 for ASCII data and cp500 or similar for EBCDIC data.
len_enc - field’s length encoding type. Follows the same rules as data_enc. Some fields, such as ICC data, could have binary data but ASCII length. This parameter does not affect fixed-length fields.
len_type - field’s length type: fixed, LVAR, LLVAR, etc. Expressed as number of bytes in field length. For example, ASCII LLVAR length takes up 2 bytes (b'00' - b'99'). BCD LLVAR length can take up only 1 byte (b'\x00' - b'\x63'). len_type depends on the type of len_enc being used. BCD len_enc can fit higher length ranges in fewer bytes.

len_type len_enc

ASCII / EBCDIC Binary-Coded Decimal

Fixed 0 0

LVAR 1 1

LLVAR 2 1

LLLVAR 3 2

LLLLVAR 4 2
max_len - field’s maximum length in bytes. For fixed fields max_len defines the fixed length of the field.
desc - field’s description that’s printed in a pretty format. desc plays no role in encoding or decoding data. It’s safe to omit it from the specifications. If omitted iso8583.pp() may or may not work as expected.

Sample Field Specifications ¶

Binary-coded decimal primary bitmap (the same applies to the secondary bitmap):

specification["p"] = {
    "data_enc": "b",
    "len_enc": "b",
    "len_type": 0,
    "max_len": 8,
    "desc": "BCD bitmap, e.g. \x12\x34\x56\x78\x90\xAB\xCD\xEF"
}

Hex string primary bitmap (the same applies to the secondary bitmap):

specification["p"] = {
    "data_enc": "ascii",
    "len_enc": "ascii",
    "len_type": 0,
    "max_len": 16,
    "desc": "Hex string bitmap, e.g 1234567890ABCDEF"
}

Field 2 that is a BCD fixed length field of 10 bytes:

specification["2"] = {
    "data_enc": "b",
    "len_enc": "b",
    "len_type": 0,
    "max_len": 10,
    "desc": "BCD fixed field"
}

Field 3 that is an ASCII LLVAR field of maximum 20 bytes:

specification["3"] = {
    "data_enc": "ascii",
    "len_enc": "ascii",
    "len_type": 2,
    "max_len": 20,
    "desc": "ASCII LLVAR field"
}

Field 4 that is an EBCDIC LLLVAR field of maximum 150 bytes:

specification["4"] = {
    "data_enc": "cp500",
    "len_enc": "cp500",
    "len_type": 3,
    "max_len": 150,
    "desc": "EBCDIC LLLVAR field"
}

Sample Message Specifications ¶

ASCII/BCD ¶

Bitmaps, MACs, PIN, and ICC data are in BCD:

default = {
"h":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 0,   "desc": "Message Header"},
"t":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Type"},
"p":   {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Bitmap, Primary"},
"1":   {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Bitmap, Secondary"},
"2":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 19,  "desc": "Primary Account Number (PAN)"},
"3":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Processing Code"},
"4":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Transaction"},
"5":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Settlement"},
"6":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Cardholder Billing"},
"7":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transmission Date and Time"},
"8":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Amount, Cardholder Billing Fee"},
"9":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Conversion Rate, Settlement"},
"10":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Conversion Rate, Cardholder Billing"},
"11":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "System Trace Audit Number"},
"12":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Time, Local Transaction"},
"13":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Local Transaction"},
"14":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Expiration"},
"15":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Settlement"},
"16":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Conversion"},
"17":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Capture"},
"18":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Merchant Type"},
"19":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Acquiring Institution Country Code"},
"20":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "PAN Country Code"},
"21":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Forwarding Institution Country Code"},
"22":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Point-of-Service Entry Mode"},
"23":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "PAN Sequence Number"},
"24":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Network International ID (NII)"},
"25":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Point-of-Service Condition Code"},
"26":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Point-of-Service Capture Code"},
"27":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "Authorizing ID Response Length"},
"28":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Transaction Fee"},
"29":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Settlement Fee"},
"30":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Transaction Processing Fee"},
"31":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Settlement Processing Fee"},
"32":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Acquiring Institution ID Code"},
"33":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Forwarding Institution ID Code"},
"34":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Primary Account Number, Extended"},
"35":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 37,  "desc": "Track 2 Data"},
"36":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 104, "desc": "Track 3 Data"},
"37":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Retrieval Reference Number"},
"38":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Authorization ID Response"},
"39":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Response Code"},
"40":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Service Restriction Code"},
"41":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Card Acceptor Terminal ID"},
"42":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 15,  "desc": "Card Acceptor ID Code"},
"43":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 40,  "desc": "Card Acceptor Name/Location"},
"44":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 25,  "desc": "Additional Response Data"},
"45":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 76,  "desc": "Track 1 Data"},
"46":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - ISO"},
"47":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - National"},
"48":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - Private"},
"49":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Transaction"},
"50":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Settlement"},
"51":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Cardholder Billing"},
"52":  {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "PIN"},
"53":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Security-Related Control Information"},
"54":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 240, "desc": "Additional Amounts"},
"55":  {"data_enc": "b",     "len_enc": "ascii", "len_type": 3, "max_len": 255, "desc": "ICC data"},
"56":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved ISO"},
"57":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"58":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"59":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"60":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"61":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"62":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"63":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"64":  {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "MAC"},
"65":  {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Bitmap, Extended"},
"66":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "Settlement Code"},
"67":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Extended Payment Code"},
"68":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Receiving Institution Country Code"},
"69":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Settlement Institution Country Code"},
"70":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Network Management Information Code"},
"71":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Number"},
"72":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Number, Last"},
"73":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Date, Action"},
"74":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Credits, Number"},
"75":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Credits, Reversal Number"},
"76":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Debits, Number"},
"77":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Debits, Reversal Number"},
"78":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transfer, Number"},
"79":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transfer, Reversal Number"},
"80":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Inquiries, Number"},
"81":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Authorizations, Number"},
"82":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Credits, Processing Fee Amount"},
"83":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Credits, Transaction Fee Amount"},
"84":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Debits, Processing Fee Amount"},
"85":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Debits, Transaction Fee Amount"},
"86":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Credits, Amount"},
"87":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Credits, Reversal Amount"},
"88":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Debits, Amount"},
"89":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Debits, Reversal Amount"},
"90":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 42,  "desc": "Original Data Elements"},
"91":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "File Update Code"},
"92":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "File Security Code"},
"93":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 5,   "desc": "Response Indicator"},
"94":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 7,   "desc": "Service Indicator"},
"95":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 42,  "desc": "Replacement Amounts"},
"96":  {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Message Security Code"},
"97":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 17,  "desc": "Amount, Net Settlement"},
"98":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 25,  "desc": "Payee"},
"99":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Settlement Institution ID Code"},
"100": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Receiving Institution ID Code"},
"101": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 17,  "desc": "File Name"},
"102": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Account ID 1"},
"103": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Account ID 2"},
"104": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 100, "desc": "Transaction Description"},
"105": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"106": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"107": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"108": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"109": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"110": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"111": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"112": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"113": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"114": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"115": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"116": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"117": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"118": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"119": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"120": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"121": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"122": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"123": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"124": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"125": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"126": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"127": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"128": {"data_enc": "b",     "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "MAC"}
}

ASCII ¶

All fields are in ASCII:

default_ascii = {
"h":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 0,   "desc": "Message Header"},
"t":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Type"},
"p":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Bitmap, Primary"},
"1":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Bitmap, Secondary"},
"2":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 19,  "desc": "Primary Account Number (PAN)"},
"3":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Processing Code"},
"4":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Transaction"},
"5":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Settlement"},
"6":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Amount, Cardholder Billing"},
"7":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transmission Date and Time"},
"8":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Amount, Cardholder Billing Fee"},
"9":   {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Conversion Rate, Settlement"},
"10":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Conversion Rate, Cardholder Billing"},
"11":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "System Trace Audit Number"},
"12":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Time, Local Transaction"},
"13":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Local Transaction"},
"14":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Expiration"},
"15":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Settlement"},
"16":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Conversion"},
"17":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Date, Capture"},
"18":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Merchant Type"},
"19":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Acquiring Institution Country Code"},
"20":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "PAN Country Code"},
"21":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Forwarding Institution Country Code"},
"22":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Point-of-Service Entry Mode"},
"23":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "PAN Sequence Number"},
"24":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Network International ID (NII)"},
"25":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Point-of-Service Condition Code"},
"26":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Point-of-Service Capture Code"},
"27":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "Authorizing ID Response Length"},
"28":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Transaction Fee"},
"29":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Settlement Fee"},
"30":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Transaction Processing Fee"},
"31":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 9,   "desc": "Amount, Settlement Processing Fee"},
"32":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Acquiring Institution ID Code"},
"33":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Forwarding Institution ID Code"},
"34":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Primary Account Number, Extended"},
"35":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 37,  "desc": "Track 2 Data"},
"36":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 104, "desc": "Track 3 Data"},
"37":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Retrieval Reference Number"},
"38":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Authorization ID Response"},
"39":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Response Code"},
"40":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Service Restriction Code"},
"41":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 8,   "desc": "Card Acceptor Terminal ID"},
"42":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 15,  "desc": "Card Acceptor ID Code"},
"43":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 40,  "desc": "Card Acceptor Name/Location"},
"44":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 25,  "desc": "Additional Response Data"},
"45":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 76,  "desc": "Track 1 Data"},
"46":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - ISO"},
"47":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - National"},
"48":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Additional Data - Private"},
"49":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Transaction"},
"50":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Settlement"},
"51":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Currency Code, Cardholder Billing"},
"52":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "PIN"},
"53":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Security-Related Control Information"},
"54":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 240, "desc": "Additional Amounts"},
"55":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 510, "desc": "ICC data"},
"56":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved ISO"},
"57":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"58":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"59":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"60":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved National"},
"61":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"62":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"63":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved Private"},
"64":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "MAC"},
"65":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Bitmap, Extended"},
"66":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "Settlement Code"},
"67":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "Extended Payment Code"},
"68":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Receiving Institution Country Code"},
"69":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Settlement Institution Country Code"},
"70":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 3,   "desc": "Network Management Information Code"},
"71":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Number"},
"72":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 4,   "desc": "Message Number, Last"},
"73":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 6,   "desc": "Date, Action"},
"74":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Credits, Number"},
"75":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Credits, Reversal Number"},
"76":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Debits, Number"},
"77":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Debits, Reversal Number"},
"78":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transfer, Number"},
"79":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Transfer, Reversal Number"},
"80":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Inquiries, Number"},
"81":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 10,  "desc": "Authorizations, Number"},
"82":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Credits, Processing Fee Amount"},
"83":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Credits, Transaction Fee Amount"},
"84":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Debits, Processing Fee Amount"},
"85":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 12,  "desc": "Debits, Transaction Fee Amount"},
"86":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Credits, Amount"},
"87":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Credits, Reversal Amount"},
"88":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Debits, Amount"},
"89":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Debits, Reversal Amount"},
"90":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 42,  "desc": "Original Data Elements"},
"91":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 1,   "desc": "File Update Code"},
"92":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 2,   "desc": "File Security Code"},
"93":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 5,   "desc": "Response Indicator"},
"94":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 7,   "desc": "Service Indicator"},
"95":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 42,  "desc": "Replacement Amounts"},
"96":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "Message Security Code"},
"97":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 17,  "desc": "Amount, Net Settlement"},
"98":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 25,  "desc": "Payee"},
"99":  {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Settlement Institution ID Code"},
"100": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 11,  "desc": "Receiving Institution ID Code"},
"101": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 17,  "desc": "File Name"},
"102": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Account ID 1"},
"103": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 2, "max_len": 28,  "desc": "Account ID 2"},
"104": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 100, "desc": "Transaction Description"},
"105": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"106": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"107": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"108": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"109": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"110": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"111": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for ISO Use"},
"112": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"113": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"114": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"115": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"116": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"117": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"118": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"119": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for National Use"},
"120": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"121": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"122": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"123": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"124": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"125": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"126": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"127": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 3, "max_len": 999, "desc": "Reserved for Private Use"},
"128": {"data_enc": "ascii", "len_enc": "ascii", "len_type": 0, "max_len": 16,  "desc": "MAC"}
}

iso8583 – Functions ¶

Table of Contents

iso8583 – Functions

Main Functions ¶

iso8583.decode(s: bytes, spec: dict) → Tuple[dict, dict][source]¶

Deserialize a bytes or bytearray instance containing ISO8583 data to a Python dict.

Parameters:

s (bytes or bytearray) – Encoded ISO8583 data
spec (dict) – A Python dict defining ISO8583 specification. See iso8583.specs module for examples.

Returns:

doc_dec (dict) – Dict containing decoded ISO8583 data
doc_enc (dict) – Dict containing encoded ISO8583 data

Raises:

DecodeError – An error decoding ISO8583 bytearray
TypeError – s must be a bytes or bytearray instance

Examples

>>> import pprint
>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b"02004010100000000000161234567890123456123456111"
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> pprint.pprint(doc_dec)
{'12': '123456',
 '2': '1234567890123456',
 '20': '111',
 'bm': {2, 12, 20},
 'p': '4010100000000000',
 't': '0200'}

iso8583.encode(doc_dec: dict, spec: dict) → Tuple[bytearray, dict][source]¶

Serialize Python dict containing ISO8583 data to a bytearray.

Parameters:

doc_dec (dict) – Dict containing decoded ISO8583 data
spec (dict) – A Python dict defining ISO8583 specification. See iso8583.specs module for examples.

Returns:

s (bytearray) – Encoded ISO8583 data
doc_enc (dict) – Dict containing encoded ISO8583 data

Raises:

EncodeError – An error encoding ISO8583 bytearray
TypeError – doc_dec must be a dict instance

Examples

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> doc_dec = {
...     't': '0210',
...     'bm': set([3, 39]),
...     '3': '111111',
...     '39': '05'}
>>> s, doc_enc = iso8583.encode(doc_dec, spec)
>>> s
bytearray(b'0210200000000200000011111105')

Exceptions ¶

exception iso8583.DecodeError(msg: str, s: bytes, doc_dec: dict, doc_enc: dict, pos: int, field: str)[source]¶

Subclass of ValueError that describes ISO8583 decoding error.

Variables:

msg (str) – The unformatted error message
s (bytes or bytearray) – The ISO8583 bytes instance being parsed
doc_dec (dict) – Dict containing partially decoded ISO8583 data
doc_enc (dict) – Dict containing partially encoded ISO8583 data
pos (int) – The start index where ISO8583 bytes data failed parsing
field (str) – The ISO8583 field where parsing failed

exception iso8583.EncodeError(msg: str, doc_dec: dict, doc_enc: dict, field: str)[source]¶

Subclass of ValueError that describes ISO8583 encoding error.

Variables:	msg (str) – The unformatted error message doc_dec (dict) – Dict containing decoded ISO8583 data being encoded doc_enc (dict) – Dict containing partially encoded ISO8583 data field (str) – The ISO8583 field where parsing failed

Helper Functions ¶

iso8583.add_field(doc_dec: dict, field: str, val: str) → None[source]¶

Add or override field and its value in ISO8583 dictionary.

Parameters:	doc_dec (dict) – Dict containing decoded ISO8583 data field (str) – Field key to be added val (str) – Field value to be added

Examples

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b"02004010100000000000161234567890123456123456840"
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> iso8583.pp(doc_dec, spec)
'bm'  Enabled Fields                      : [2, 12, 20]
't'   Message Type                        : [0200]
'p'   Bitmap, Primary                     : [4010100000000000]
'2'   Primary Account Number (PAN)        : 16 [1234567890123456]
'12'  Time, Local Transaction             : [123456]
'20'  PAN Country Code                    : [840]
>>> iso8583.add_field(doc_dec, "t", "0210")
>>> iso8583.add_field(doc_dec, "39", "00")
>>> s, doc_enc = iso8583.encode(doc_dec, spec)
>>> iso8583.pp(doc_dec, spec)
'bm'  Enabled Fields                      : [2, 12, 20, 39]
't'   Message Type                        : [0210]
'p'   Bitmap, Primary                     : [4010100002000000]
'2'   Primary Account Number (PAN)        : 16 [1234567890123456]
'12'  Time, Local Transaction             : [123456]
'20'  PAN Country Code                    : [840]
'39'  Response Code                       : [00]

iso8583.del_field(doc_dec: dict, field: str) → Any[source]¶

Delete field from ISO8583 dictionary.

Parameters:	doc_dec (dict) – Dict containing decoded ISO8583 data field (int or str) – Field key to be deleted
Returns:	Deleted field value. None if the field did not exist.
Return type:	Key Value or None

Examples

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b"02004010100000000000161234567890123456123456840"
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> iso8583.pp(doc_dec, spec)
'bm'  Enabled Fields                      : [2, 12, 20]
't'   Message Type                        : [0200]
'p'   Bitmap, Primary                     : [4010100000000000]
'2'   Primary Account Number (PAN)        : 16 [1234567890123456]
'12'  Time, Local Transaction             : [123456]
'20'  PAN Country Code                    : [840]
>>> iso8583.del_field(doc_dec, "20")
'840'
>>> s, doc_enc = iso8583.encode(doc_dec, spec)
>>> iso8583.pp(doc_dec, spec)
'bm'  Enabled Fields                      : [2, 12]
't'   Message Type                        : [0200]
'p'   Bitmap, Primary                     : [4010000000000000]
'2'   Primary Account Number (PAN)        : 16 [1234567890123456]
'12'  Time, Local Transaction             : [123456]

iso8583.pp(doc_dec: dict, spec: dict, desc_width: int = 36, stream: IO[AnyStr] = None) → None[source]¶

Pretty Print Python dict containing decoded ISO8583 data.

Parameters:

doc_dec (dict) – Dict containing decoded ISO8583 data
spec (dict) – A Python dict defining ISO8583 specification. See iso8583.specs module for examples.
desc_width (int, optional) – Width of field description that’s printed (default 36). Specify 0 to print no descriptions.
stream (stream, optional) – An output stream. The only method used on the stream object is the file protocol’s write() method. If not specified, the iso8583.pp() adopts sys.stdout.

Notes

For iso8583.pp() to work in all circumstances it’s recommended to be used after iso8583.encode() or iso8583.decode().

Examples

>>> import iso8583
>>> from iso8583.specs import default_ascii as spec
>>> s = b"02004010100000000000161234567890123456123456840"
>>> doc_dec, doc_enc = iso8583.decode(s, spec)
>>> iso8583.pp(doc_dec, spec)
'bm'  Enabled Fields                      : [2, 12, 20]
't'   Message Type                        : [0200]
'p'   Bitmap, Primary                     : [4010100000000000]
'2'   Primary Account Number (PAN)        : 16 [1234567890123456]
'12'  Time, Local Transaction             : [123456]
'20'  PAN Country Code                    : [840]

iso8583 – Change Log¶

1.0.2 - 2020-01-11¶

Optional proprietary header can now be parsed using standard field settings
Documentation improvements

1.0.1 - 2019-11-11¶

iso8583.decode and iso8583.decode now return a tuple
iso8583.decode returns a tuple of decoded dict instance and encoded dict instance
iso8583.encode returns a tuple of encoded bytes instance and encoded dict instance
Encoded and decoded dict instance keys are now all strings
Specification keys are now all strings

1.0.0 - 2019-11-04¶

Initial release.

ISO8583 is an international standard for financial transaction card originated interchange messaging. It is the ISO standard for systems that exchange electronic transactions initiated by cardholders using payment cards.

iso8583 serializes and deserializes ISO8583 data between a bytes or bytearray instance containing ISO8583 data and a Python dict.

len_type	len_enc
len_type	ASCII / EBCDIC	Binary-Coded Decimal
Fixed	`0`	`0`
LVAR	`1`	`1`
LLVAR	`2`	`1`
LLLVAR	`3`	`2`
LLLLVAR	`4`	`2`