go8583

Go library for ISO8583 message packing/unpacking, dynamic JSON packager loading, and BER-TLV handling (including DE55 workflows).

This development is inspired by jPOS: https://github.com/jpos/jPOS

Looking for in-depth docs? See the project knowledge base in docs/ — architecture, packager internals, field-packager catalog, TLV/DE55 guide, cookbook, testing, and a glossary.

Installation

go get github.com/sachingimhan/go8583@latest

import iso8583 "github.com/sachingimhan/go8583"

Then run:

go mod tidy

Core Capabilities

• Build ISO8583 messages with ISOMsg
• Pack/unpack using BasePackager or JSON-driven packagers
• Support for ASCII, BCD, binary, EBCDIC, bitmap, amount, and subfield formats
• BER-TLV encode/decode utilities
• TLVList API for DE55 build, parse, search, update, and serialize

Sample JSON packager definitions used by tests are in:

• testdata/packagers/cup_packager.json
• testdata/packagers/visa_packager.json
• testdata/packagers/mastercard_packager.json

Quick Start: JSON Packager + Message

jsonCfg := `{
  "fields": [
    {"id": 0, "length": 4, "name": "MTI", "class": "IFA_NUMERIC"},
    {"id": 1, "length": 16, "name": "BITMAP", "class": "IFA_BITMAP"},
    {"id": 2, "length": 19, "name": "PAN", "class": "IFA_LLCHAR"},
    {"id": 3, "length": 6, "name": "PROC", "class": "IFA_NUMERIC"},
    {"id": 4, "length": 12, "name": "AMOUNT", "class": "IFA_NUMERIC"}
  ]
}`

p, _ := iso8583.NewGenericPackagerFromReader(strings.NewReader(jsonCfg))

m := iso8583.NewISOMsg()
m.Set(0, "0200")
m.Set(2, "4567890123456789")
m.Set(3, "000000")
m.Set(4, "1000")

raw, _ := p.Pack(m)

out := iso8583.NewISOMsg()
_, _ = p.Unpack(out, raw)

Quick Start: DE55 TLV List

tl := iso8583.NewTLVList()
_ = tl.AppendHex(0x9F02, "000000159500")
_ = tl.AppendHex(0x5F2A, "0144")
_ = tl.AppendHex(0x9F1A, "0144")

de55, _ := tl.Pack()

parsed, _ := iso8583.ParseTLVList(de55)
for _, item := range parsed.Elements() {
	fmt.Printf("Tag: %X Value: %s\n", item.GetTag(), item.GetStringValue())
}

API Reference

Core Message API

ISOMsg:

• NewISOMsg() *ISOMsg
• (m *ISOMsg) Set(id any, val any)
• (m *ISOMsg) SetMTI(val string)
• (m *ISOMsg) Get(id any) ISOComponent
• (m *ISOMsg) GetString(id any) string
• (m *ISOMsg) GetBytes(id any) []byte
• (m *ISOMsg) HasField(id any) bool
• (m *ISOMsg) Pack() ([]byte, error)
• (m *ISOMsg) Unpack(data []byte) (int, error)
• (m *ISOMsg) GetValue() any

ISOField:

• (f *ISOField) Pack() ([]byte, error)
• (f *ISOField) Unpack(data []byte) (int, error)
• (f *ISOField) GetValue() any

Interfaces:

• ISOComponent
• ISOPackager
• ISOFieldPackager

Packager Loading API

• NewGenericPackager(path string) (*BasePackager, error)
• NewGenericPackagerFromReader(r io.Reader) (*BasePackager, error)
• NewGenericPackagerFromConfig(config *PackagerConfig) (*BasePackager, error)

BasePackager methods:

• (p *BasePackager) Pack(m *ISOMsg) ([]byte, error)
• (p *BasePackager) Unpack(m *ISOMsg, data []byte) (int, error)
• (p *BasePackager) PackField(fld int, value any) ([]byte, error)
• (p *BasePackager) UnpackField(fld int, data []byte, offset int) (any, int, error)
• (p *BasePackager) GetFieldPackager(fld int) ISOFieldPackager
• (p *BasePackager) GetLength() int

Config structs:

• type PackagerConfig struct { Fields []FieldConfig }
• type FieldConfig struct { ID, Length, Name, Class, Fields, Packager }

Registry:

• var PackagerRegistry map[string]func(int) ISOFieldPackager

Field Packager Constructors

ASCII/EBCDIC/BCD/Binary constructors:

• NewIFANumeric
• NewIFALLChar
• NewIFA_LLNUM
• NewIFA_LLLNUM
• NewIFA_LLLCHAR
• NewIFB_NUMERIC
• NewIFB_LLNUM
• NewIFB_LLLNUM
• NewIFB_LLHNUM
• NewIFB_LLCHAR
• NewIFB_LLLCHAR
• NewIFB_LLHCHAR
• NewIFB_LLHECHAR
• NewIFB_LLHBINARY
• NewIFB_LLLHBINARY
• NewIFB_LLLBINARY
• NewIFB_LLLLBINARY
• NewIFB_BINARY
• NewIFB_AMOUNT
• NewIFB_LL_HEX_NUMERIC
• NewIFA_BINARY
• NewIFA_LLLBINARY
• NewIFA_AMOUNT
• NewIFE_NUMERIC
• NewIFE_CHAR
• NewIFE_LLCHAR
• NewIFE_LLNUM
• NewIFE_LLLCHAR
• NewIFE_LLLBINARY
• NewIFE_AMOUNT
• NewIF_CHAR
• NewIF_ECHAR
• NewIFMC_LLCHAR
• NewIFMC_LLLCHAR

Bitmap/subfield/TLV constructors:

• NewIFB_LLH_SUBPACKAGER
• NewIFA_LLLTLV
• NewIFB_LLHTLV

Special packager types:

• IFABitmap
• IFB_BITMAP
• IF_NOP
• Base1_BITMAP126
• BCDSubFieldPackager
• TLVFieldPackager
• ISOStringFieldPackager

TLV API

Single TLV item:

• NewTLV(tag int, value []byte) (TLV, error)
• NewTLVWithFormat(tag int, value []byte, tagSize int, lengthSize int) (TLV, error)
• (t TLV) GetTag() int
• (t TLV) GetValue() []byte
• (t TLV) GetTLV() ([]byte, error)
• (t TLV) GetTLVWithFormat(tagSize int, lengthSize int) ([]byte, error)
• (t TLV) GetL() ([]byte, error)
• (t TLV) GetLWithSize(lengthSize int) ([]byte, error)
• (t TLV) GetStringValue() string
• (t TLV) IsPrimitive() bool
• (t TLV) String() string

TLV encode/decode helpers:

• PackTLV
• PackTLVWithFormat
• PackTLVs
• PackTLVsWithFormat
• UnpackTLV
• UnpackTLVWithFormat
• UnpackTLVs
• UnpackTLVsWithFormat
• ParseTLVHex
• EncodeTLVHex
• FindTLVByTag
• FindTLVValueByTag
• GetTLVTags
• GetTLVValues

TLV list API (TLVList):

• CreateTLVListBuilder() *TLVListBuilder
• NewTLVList() *TLVList
• NewTLVListWithFormat(tagSize int, lengthSize int) (*TLVList, error)
• NewTLVListFromTLVs(tags []TLV) *TLVList
• ParseTLVList(buf []byte) (*TLVList, error)
• ParseTLVListWithFormat(buf []byte, tagSize int, lengthSize int) (*TLVList, error)
• (tl *TLVList) Unpack(buf []byte) error
• (tl *TLVList) UnpackOffset(buf []byte, offset int) error
• (tl *TLVList) Pack() ([]byte, error)
• (tl *TLVList) Append(tag int, value []byte) error
• (tl *TLVList) AppendHex(tag int, value string) error
• (tl *TLVList) AppendTLV(tlv TLV) error
• (tl *TLVList) GetTags() []TLV
• (tl *TLVList) Elements() []TLV
• (tl *TLVList) Find(tag int) (TLV, bool)
• (tl *TLVList) FindIndex(tag int) int
• (tl *TLVList) FindNextTLV() (TLV, bool, error)
• (tl *TLVList) Index(index int) (TLV, error)
• (tl *TLVList) GetValue(tag int) ([]byte, bool)
• (tl *TLVList) GetString(tag int) (string, bool)
• (tl *TLVList) HasTag(tag int) bool
• (tl *TLVList) DeleteByIndex(index int) error
• (tl *TLVList) DeleteByTag(tag int)
• (tl *TLVList) Len() int
• (tl *TLVList) Dump(w io.Writer, indent string)

TLVListBuilder:

• (b *TLVListBuilder) FixedTagSize(tagSize int) *TLVListBuilder
• (b *TLVListBuilder) FixedLengthSize(lengthSize int) *TLVListBuilder
• (b *TLVListBuilder) Build() (*TLVList, error)

Strategy Utilities API

Interpreters:

• AsciiInterpreter
• BcdInterpreter
• EbcdicInterpreter
• BinaryInterpreter

Prefixers:

• AsciiPrefixer
• BcdPrefixer
• BinaryPrefixer
• EbcdicPrefixer

Padders:

• LeftPadder
• RightPadder

Interfaces:

• Interpreter
• Prefixer
• Padder

ISO Utility API

ISOUtil methods:

• (u ISOUtil) AsciiToEbcdic(ascii string) []byte
• (u ISOUtil) EbcdicToAscii(ebcdic []byte) string
• (u ISOUtil) HexToBytes(h string) ([]byte, error)
• (u ISOUtil) BytesToHex(b []byte) string
• (u ISOUtil) ZeroPad(s string, length int) string
• (u ISOUtil) SpacePad(s string, length int) string
• (u ISOUtil) StrToHex(s string) string
• (u ISOUtil) HexToStr(h string) (string, error)
• (u ISOUtil) StrToBCD(s string) []byte
• (u ISOUtil) BCDToStr(b []byte) string

JSON Packager Class Keys

These class values are available in PackagerRegistry:

• IFA_NUMERIC
• IFA_LLCHAR
• IFA_BITMAP
• IFB_NUMERIC
• IFB_LLNUM
• IFB_BITMAP
• IFA_LLNUM
• IFA_LLLCHAR
• IFB_LLLNUM
• IFE_NUMERIC
• IFE_CHAR
• IFE_LLCHAR
• IFE_LLNUM
• IFE_LLLCHAR
• IFA_BINARY
• IFB_BINARY
• IF_CHAR
• IFA_AMOUNT
• IFE_AMOUNT
• IFB_AMOUNT
• IFB_LLHNUM
• IFB_LLHCHAR
• IFB_LLLHBINARY
• IFB_LLHECHAR
• IFB_LLHBINARY
• IFB_LLCHAR
• IFMC_LLCHAR
• IFMC_LLLCHAR
• IFE_LLLBINARY
• IFB_LLLCHAR
• IF_ECHAR
• IFB_LL_HEX_NUMERIC
• IFA_LLLBINARY
• IFB_LLLBINARY
• IFB_LLLLBINARY
• IFA_LLLTLV
• IFB_LLHTLV
• TLV
• IFA_LLLNUM
• IF_NOP
• Base1_BITMAP126

Tests

Run all tests:

go test ./...

Run TLV-focused tests:

go test ./... -run "TestTLV|TestTLVList|TestPrintAllTagsAndValuesFromUnpackedTLV" -v