ut-codec-iso8583

ISO 8583 codec

Scope

Implement encoding and decoding of ISO 8583 messages from/to buffers, usually to be exchanged over a TCP socket. Wikipedia has some documentation for the standard.

Usage

Usually used together with ut-port-tcp, for example like this:

module.exports = {
    createPort: require('ut-port-tcp'),
    format: {
        size: '16/integer',
        codec: require('ut-codec-iso8583'),
        version: 0,
        baseEncoding: 'ascii',
        fieldFormat: {
            '37': {format: 'numeric'}
        }
    }
}

In the format configuration property, the following settings are often used:

• size - specifies the format for the message size header and is mandatory to be specified
• version - specifies the ISO 8583 version to be used
• baseEncoding - specifies one of the 2 most common base encodings to use: ascii or binary, with ascii being default
• fieldFormat - in this object, overrides for the format of specific fields can be specified. If not specified, a default format for the version and baseEncoding will be used. The default formats are in the file fields.json

Public API

The module exposes Iso8583 class.

decode

(buffer, $meta, context, log)

Decodes ISO8583 format message to object

params

• buffer (buffer) - ISO8583 encoded message
• $meta (object) - meta object as defined in ???
• context (object) - context object as defined in ???
• log (object) - log functions as defined in ut-log

result (object)

• header (string) - message header
• mtid (string) - message type indicator according to ISO8583 specifications
• rawData (buffer) - message in ISO8583 format
• 0 (string) - primary bitmap
• 1 (string) - secondary bitmap
• rest - depending on data elements 0 and 1 contains ISO8583 data elements as key: value pairs as follows:
  • key - ISO8583 element index
  • value (string) - ISO8583 element value

encode

(message, $meta, context, log)

Encodes message object to ISO8583 format

params

• message (object) - each key: value pair contains the following:
  • key - ISO8583 element index
  • value (string) - ISO8583 element value
• $meta (object) - meta object as defined in ???
• context (object) - context object as defined in ???
• log (object) - log functions as defined in ut-log

result (buffer) - ISO8583 encoded message

Field format definition

Each ISO8583 field is defined in the following object:

• key - ISO8583 element index, including header, footer, mtid and primary bitmap 0
• value (object) - data element definition
  • size (integer) - size of the data element value in number of symbols
  • name (string) - descriptive field name
  • format (string) - data format of the value
  • prefixSize (integer) - number of symbols indicating the size of the variable length data elements; NOTE: available only for (and also indicating) variable length data elements

Configuration

• defineError (function) - defineError function as defined in ut-error
• getError (function) - getError function as defined in ut-error
• fetchErrors (function) - fetchErrors function as defined in ut-error
• maskFields (array) - contains ISO8583 element indexes which will be masked in ISO8583 encoded messages
  • (string) - ISO8583 data element
• networkCodes () - ???
• emvParser () - ???
• successResponseIdentifier (string) - error code for successful processing (no-error code)
• version (string) - ISO8583 version; Valid values: 0 (1987), 1 (1993), 2 (2003)
• baseEncoding (string) - ISO8583 message encoding; Valid values: ascii, binary
• fieldFormat (object) - ISO8583 field format definition to overwrite the default format; NOTE: for more information please check Field format definition above
• networkCodeField (integer) - ???
• mtidRouteMap (???) - ???