ISO8583 Utils

A TypeScript library for ISO 8583 financial message packing and unpacking.

Installation

npm install iso8583-utils

Usage

Basic Usage

import { Iso8583Utils } from '@anggit97/iso8583-utils';
import type { Iso8583Spec } from '@anggit97/iso8583-utils';

// Provide your own spec at runtime
const spec: Iso8583Spec = {
  2: { type: 'LLVAR', length: 19 },
  3: { type: 'N', length: 6 },
  4: { type: 'N', length: 12 },
  // ...
};

const isoUtils = new Iso8583Utils(spec);

// Pack a message (MTI is now in field 0)
const data = {
  0: "0200",                // Message Type Identifier (MTI)
  2: "622011444444444444",  // Primary Account Number
  3: "500001",              // Processing Code
  4: "000000250000",        // Amount
  7: "0528061410",          // Transmission Date & Time
  11: "062519",             // STAN
  // ... other fields
};

const packedMessage = isoUtils.pack(data);
console.log(packedMessage);

// Pack with message length header and ETX terminator
const packedWithHeader = isoUtils.pack(data, true, 0, { appendEtx: true, validate: true });
console.log(packedWithHeader); // "00740200722000000000000018622011444444444444500001..."

// Unpack a message
const unpacked = isoUtils.unpack(packedMessage);
console.log(unpacked.mti);    // "0200"
console.log(unpacked.data);   // All fields including field 0 (MTI)

// Unpack message with header
const unpackedWithHeader = isoUtils.unpack(packedWithHeader, true);
console.log(unpackedWithHeader.mti); // "0200"

Custom Specification

import { Iso8583Utils, FieldSpec, Iso8583Spec } from 'iso8583-utils';

// Define your own specification
const customSpec: Iso8583Spec = {
  2: { type: "LLVAR", length: 19 },
  3: { type: "N", length: 6 },
  4: { type: "N", length: 12 },
  // ... other fields
};

const isoUtils = new Iso8583Utils(customSpec);

API Reference

Iso8583Utils

Constructor

• new Iso8583Utils(spec: Iso8583Spec) - Initialize with a field specification

Methods

• pack(data: Record<number, unknown>, includeHeader?: boolean): string - Pack data into ISO 8583 message (MTI in field 0)
• unpack(rawMessage: string, hasHeader?: boolean): Iso8583Message - Unpack ISO 8583 message

Types

• FieldType - "N" | "AN" | "ANS" | "LLVAR" | "LLLVAR"
• FieldSpec - Interface for field specification
• Iso8583Spec - Record of field specifications
• Iso8583Message - Interface for unpacked message with MTI and data

Field Types

• N: Numeric (fixed length)
• AN: Alphanumeric (fixed length)
• ANS: Alphanumeric with special characters (fixed length)
• LLVAR: Variable length with 2-digit length prefix
• LLLVAR: Variable length with 3-digit length prefix

Message Header

The library supports optional message length headers for network transmission:

• Without Header: pack(data) - Standard ISO 8583 message
• With Header: pack(data, true) - Adds 4-digit length prefix
• Unpack: unpack(message, hasHeader) - Set hasHeader=true if message has length prefix

Example:

// Pack with header
const withHeader = isoUtils.pack(data, true);
// Result: "00740200722000000000000018622011444444444444500001..."
//         ^^^^
//         Length header (74 characters)

// Unpack with header
const unpacked = isoUtils.unpack(withHeader, true);

License

MIT