ISO Parser CLI

hard · iso8583, payments

ISO8583 Parser Capstone

Build the supplied parser library for an explicit synthetic message profile. The historical slug says CLI; a terminal interface is not graded. The profiles are teaching examples, not complete network specifications. Keep all supplied types and function signatures. No encoding auto-detection is required.

Core Data Structures

// MessageSpec defines how to parse messages for a specific network
type MessageSpec struct {
    Name           string              // e.g., "ISO8583:1987 Base"
    BitmapEncoding string              // "BINARY" or "HEX_ASCII"
    Fields         map[int]*FieldSpec  // Field definitions
}

// FieldSpec defines how to parse a single data element
type FieldSpec struct {
    Number     int     // Field number (2-128)
    Name       string  // Human-readable name
    LengthType string  // "FIXED", "LLVAR", "LLLVAR"
    MaxLength  int     // Maximum length
    DataType   string  // "N", "AN", "ANS", "B"
    Encoding   string  // "ASCII", "BCD", "BINARY"
}

// ParsedMessage is the result of parsing
type ParsedMessage struct {
    MTI        MTI                     // Parsed message type indicator
    Bitmap     Bitmap                  // Primary and optional secondary bitmap
    Fields     map[int]*ParsedField    // Parsed data elements
    Warnings   []string                // Non-fatal issues encountered
}

// MTI contains the parsed message type indicator
type MTI struct {
    Raw      string // "0100"
    Version  int    // 0=1987, 1=1993, 2=2003
    Class    int    // 1=auth, 2=financial, 4=reversal, 8=network
    Function int    // 0=request, 1=response, 2=advice, etc.
    Origin   int    // 0=acquirer, 1=acquirer repeat, etc.
}

// Bitmap tracks which fields are present
type Bitmap struct {
    Primary   []byte  // 8 bytes
    Secondary []byte  // 8 bytes if bit 1 is set
    Fields    []int   // List of present field numbers
}

// ParsedField holds a single parsed data element
type ParsedField struct {
    Number   int     // Field number
    RawHex   string  // Raw bytes as hex string
    Decoded  string  // Human-readable decoded value
}

Functions to Implement

// NewParser creates a parser with the given specification
func NewParser(spec *MessageSpec) *Parser

// Parse parses a hex string into a structured message
// The input is hex of the entire wire message, beginning "30313030" for ASCII 0100.
func (p *Parser) Parse(hexStr string) (*ParsedMessage, error)

// PrettyPrint returns a human-readable string representation
func (msg *ParsedMessage) PrettyPrint() string

// ToJSON returns a JSON representation
func (msg *ParsedMessage) ToJSON() ([]byte, error)

// DefaultSpec returns the course binary-bitmap profile
func DefaultSpec() *MessageSpec

// VisaSpec returns the synthetic course hex-ASCII profile (legacy name)
func VisaSpec() *MessageSpec

Complete-message parsing contract

NewParser stores the supplied profile; Parse returns an error for a nil profile or a bitmap encoding other than BINARY or HEX_ASCII.
Trim outer whitespace and allow internal ASCII spaces in the hex input. Hex decode the entire input once. The wire MTI is exactly four ASCII digits.
Read 8 binary or 16 hex-ASCII bytes per bitmap, including a secondary bitmap if bit 1 is set. Report set bits in increasing order, including bit 1 as an indicator, but do not parse it as a data field. This model stops at field 128.
Parse present fields in increasing order. Fixed length is MaxLength. Variable prefixes are exactly 2, 3, or 4 ASCII decimal digits for LLVAR, LLLVAR, LLLLVAR. Signs and whitespace are not decimal digits. Reject lengths over MaxLength.
Length units are bytes for ASCII/BINARY and decimal digits for BCD. BCD uses ceil(digits/2) bytes, decimal nibbles only, and a leading zero pad for odd lengths. Thus five digits encoded as 01 23 45 decode to 12345.
Reject negative MaxLength, mismatched FieldSpec.Number, missing/nil field definitions and unsupported length/data encodings. DataType is descriptive; the task does not implement business validation for every field.
RawHex is lowercase hex of payload bytes only, excluding the length prefix. ASCII Decoded is text; BINARY Decoded is uppercase hex; BCD Decoded is digits.
Stop at the first field error; do not guess a later field's start. Return the partial message containing only complete earlier fields AND a non-nil error identifying field number and wire offset. Also append this diagnostic to Warnings. Header errors may return a nil message.
Reject trailing bytes after the last field with a non-nil error. Nil error means exactly one complete message was parsed. No malformed input may panic.

Byte-exact example

wire := append([]byte("0100"), []byte{0x70, 0, 0, 0, 0, 0, 0, 0}...)
wire = append(wire, []byte("16" + "1234567890123456" + "000000" + "000000001234")...)
msg, err := NewParser(DefaultSpec()).Parse(hex.EncodeToString(wire))

This is 48 wire bytes and 96 hex characters. It contains fields 2,3,4; their payloads begin at offsets 14,30,36. Replacing the bitmap with the sixteen ASCII characters 7000000000000000 requires VisaSpec and adds eight wire bytes. Its name is retained only for compatibility.

Diagnostic display contract

PrettyPrint includes MTI, bitmap, sorted fields and warnings. ToJSON keeps the existing mti, bitmap, fields, optional warnings structure; every field view has name, raw, decoded. Both formats use the same policy:

DE2: decoded shows first six/last four digits only for length >10, with * between; otherwise mask every digit. Raw is [REDACTED].
DE52: decoded is [ENCRYPTED PIN DATA]; raw is [REDACTED].
Allow displayed raw/value data only for fields 3,4,5,6,7,11,12,13,14,22,23, 25,26,32,37,38,39,41,42,43,49,50,51,90. Display raw as uppercase hex.
All other fields (including track, ICC/private, MAC and unknown fields) show [REDACTED] in both raw and decoded views.
Amounts 4,5,6 keep their original digits with a minor-unit label. Do not infer a decimal scale without a currency exponent. Retain response-code and currency descriptions for the supplied course lookup tables.
Formatting must not mutate ParsedField.RawHex or Decoded. These views are intentionally lossy and cannot be used for retransmission or MAC calculation.

Use synthetic fixtures. Passing these tests establishes the course parsing and display contract, not a production certification or transaction approval.

Field Specification Reference

The DefaultSpec() should include at minimum these critical fields:

Field	Name	Length Type	Max	Data Type
2	Primary Account Number	LLVAR	19	N
3	Processing Code	FIXED	6	N
4	Amount, Transaction	FIXED	12	N
7	Transmission Date/Time	FIXED	10	N
11	System Trace Audit Number	FIXED	6	N
12	Time, Local Transaction	FIXED	6	N
13	Date, Local Transaction	FIXED	4	N
14	Date, Expiration	FIXED	4	N
22	POS Entry Mode	FIXED	3	N
23	Card Sequence Number	FIXED	3	N
25	POS Condition Code	FIXED	2	N
26	POS PIN Capture Code	FIXED	2	N
32	Acquiring Institution ID	LLVAR	11	N
35	Track 2 Data	LLVAR	37	Z
37	Retrieval Reference Number	FIXED	12	AN
38	Authorization ID Response	FIXED	6	AN
39	Response Code	FIXED	2	AN
41	Card Acceptor Terminal ID	FIXED	8	ANS
42	Card Acceptor ID	FIXED	15	ANS
43	Card Acceptor Name/Location	FIXED	40	ANS
49	Currency Code, Transaction	FIXED	3	N
52	PIN Data	FIXED	8	B
55	ICC Related Data	LLLVAR	999	B
64	MAC	FIXED	8	B

The default map also includes DE90 (42 ASCII bytes) and DE128 (8 binary bytes). VisaSpec uses the same field definitions and HEX_ASCII bitmap encoding.

Independent checkpoints

Derive a fresh complete cursor table before implementing the field loop.
Remove DE3 from a profile for a message containing DE2,3,4. Prove DE4 is not published, because its starting offset is unknown.
Check signed prefixes, truncated fields, odd BCD, trailing bytes and nil specs.
Search both display formats for sensitive text AND its hex representation.

The lesson provides a worked trace and progressive hints; complete the functions independently and use the checkpoint to diagnose a wrong boundary.

package solution

import (
	"encoding/json"
)

// MessageSpec defines how to parse messages for a specific network/version
type MessageSpec struct {
	Name           string             // e.g., "ISO8583:1987 Base"
	BitmapEncoding string             // "BINARY" or "HEX_ASCII"
	Fields         map[int]*FieldSpec // Field definitions indexed by field number
}

// FieldSpec defines how to parse a single data element
type FieldSpec struct {
	Number     int    // Field number (2-128)
	Name       string // Human-readable name
	LengthType string // "FIXED", "LLVAR", "LLLVAR", "LLLLVAR"
	MaxLength  int    // Maximum length for variable fields, exact length for fixed
	DataType   string // "N" (numeric), "AN" (alphanumeric), "ANS" (alphanum+special), "B" (binary)
	Encoding   string // "ASCII", "BCD", "BINARY"
}

// ParsedMessage contains completed fields, possibly alongside a parse error
type ParsedMessage struct {
	MTI      MTI                  // Parsed message type indicator
	Bitmap   Bitmap               // Primary and optional secondary bitmap
	Fields   map[int]*ParsedField // Parsed data elements indexed by field number
	Warnings []string             // Diagnostics; incomplete parsing also returns a non-nil error
}

// MTI contains the parsed message type indicator
type MTI struct {
	Raw      string // Original 4-character string (e.g., "0100")
	Version  int    // 0=1987, 1=1993, 2=2003
	Class    int    // 1=auth, 2=financial, 4=reversal, 8=network
	Function int    // 0=request, 1=response, 2=advice, etc.
	Origin   int    // 0=acquirer, 1=acquirer repeat, etc.
}

// Bitmap tracks which data elements are present in the message
type Bitmap struct {
	Primary   []byte // 8 bytes (always present)
	Secondary []byte // 8 bytes (present if bit 1 of primary is set)
	Fields    []int  // Sorted list of present field numbers
}

// ParsedField holds a single parsed data element
type ParsedField struct {
	Number  int    // Field number (e.g., 2, 4, 11)
	RawHex  string // Raw bytes as hex string
	Decoded string // Human-readable decoded value
}

// Parser parses ISO8583 messages according to a specification
type Parser struct {
	spec *MessageSpec
}

// NewParser creates a parser with the given specification
func NewParser(spec *MessageSpec) *Parser {
	// TODO: Implement
	return nil
}

// Parse parses a hex string into a structured message
// The input is a hex string like "303130307000000000000000..."
// Returns nil error only after a complete parse; partial diagnostics accompany a non-nil error.
func (p *Parser) Parse(hexStr string) (*ParsedMessage, error) {
	// TODO: Implement
	//
	// Steps:
	// 1. Validate and decode hex string to bytes
	// 2. Parse MTI (first 4 bytes for ASCII encoding)
	// 3. Parse bitmap (check encoding: BINARY = 8 bytes, HEX_ASCII = 16 chars)
	// 4. Check bit 1 for secondary bitmap
	// 5. Extract list of present fields from bitmap
	// 6. Parse each field according to its spec
	// 7. Stop on unknown/malformed fields or trailing bytes; return partial message plus error.
	//
	return nil, nil
}

// PrettyPrint returns a human-readable string representation of the message
func (msg *ParsedMessage) PrettyPrint() string {
	// TODO: Implement
	//
	// Format should include:
	// - Header with parser name
	// - MTI with decoded meaning (version, class, function, origin)
	// - Bitmap as hex with list of present fields
	// - Fields formatted through the shared allowlist/redaction policy in the statement
	// - Amounts stay in minor units; mask PAN and redact its raw hex; redact sensitive/unknown fields
	// - Any warnings at the end
	//
	return ""
}

// ToJSON returns a redacted diagnostic view using the same policy as PrettyPrint
func (msg *ParsedMessage) ToJSON() ([]byte, error) {
	// TODO: Implement
	//
	// Structure:
	// {
	//   "mti": { "raw": "0100", "version": 0, "class": 1, "function": 0, "origin": 0 },
	//   "bitmap": { "primary": "723a...", "secondary": "...", "fields": [2,3,4,...] },
	//   "fields": {
	//     "2": { "name": "Primary Account Number", "raw": "...", "decoded": "..." },
	//     ...
	//   },
	//   "warnings": [...]
	// }
	//
	return json.MarshalIndent(nil, "", "  ")
}

// DefaultSpec returns the synthetic course binary-bitmap profile
// This includes the most common fields used in authorization messages
func DefaultSpec() *MessageSpec {
	// TODO: Implement
	//
	// Return a MessageSpec with:
	// - Name: "ISO8583:1987 Base"
	// - BitmapEncoding: "BINARY"
	// - Fields: At minimum, define specs for fields 2-4, 7, 11-14, 22-26, 32, 35, 37-39, 41-43, 49, 52, 64
	//
	// Example field spec:
	// &FieldSpec{
	//     Number: 2,
	//     Name: "Primary Account Number",
	//     LengthType: "LLVAR",
	//     MaxLength: 19,
	//     DataType: "N",
	//     Encoding: "ASCII",
	// }
	//
	return nil
}

// VisaSpec is a legacy name for the synthetic course HEX_ASCII profile.
// It does not specify an actual Visa network protocol.
func VisaSpec() *MessageSpec {
	// TODO: Implement
	//
	// Similar to DefaultSpec but with:
	// - Name: a nonempty label identifying this as a course profile
	// - BitmapEncoding: "HEX_ASCII"
	// - Uses the same field layout as the synthetic DefaultSpec
	//
	return nil
}

// Helper functions you may want to implement:

// parseMTI parses the Message Type Indicator from the start of the data
// Returns the parsed MTI, number of bytes consumed, and any error
func parseMTI(data []byte) (MTI, int, error) {
	// TODO: Implement
	return MTI{}, 0, nil
}

// parseBitmap parses the primary (and optional secondary) bitmap
// encoding should be "BINARY" or "HEX_ASCII"
// Returns the parsed Bitmap, number of bytes consumed, and any error
func parseBitmap(data []byte, encoding string) (Bitmap, int, error) {
	// TODO: Implement
	return Bitmap{}, 0, nil
}

// extractFields returns a sorted list of field numbers present in the bitmap
func extractFields(bitmap *Bitmap) []int {
	// TODO: Implement
	//
	// For each bit position 1-64 in primary bitmap:
	//   byteIndex = (pos-1) / 8
	//   bitIndex = 7 - ((pos-1) % 8)
	//   if bitmap.Primary[byteIndex] & (1 << bitIndex) != 0: field is present
	//
	// If secondary bitmap exists, repeat for positions 65-128
	//
	return nil
}

// parseField parses a single field according to its specification
// Returns the parsed field, number of bytes consumed, and any error
func parseField(data []byte, spec *FieldSpec) (*ParsedField, int, error) {
	// TODO: Implement
	//
	// For FIXED: read MaxLength units (digits for BCD, bytes otherwise)
	// For LLVAR: read 2 ASCII bytes as length, then read that many bytes
	// For LLLVAR: read 3 ASCII bytes as length, then read that many bytes
	//
	// Decode based on spec.Encoding:
	// - ASCII: convert bytes to string
	// - BCD: reject nondecimal nibbles and remove a required leading zero pad for odd lengths
	// - BINARY: keep as hex representation
	//
	return nil, 0, nil
}

// formatAmount retains minor-unit digits; this API has no currency exponent.
func formatAmount(amount string) string {
	// TODO: Implement
	return amount
}

// maskPAN masks a PAN showing first 6 and last 4 digits (e.g., "4532101234567890" -> "453210******7890")
func maskPAN(pan string) string {
	// TODO: Implement
	return pan
}

// responseCodeMeaning returns the human-readable meaning of a response code
func responseCodeMeaning(code string) string {
	// TODO: Implement
	//
	// Common codes:
	// "00" -> "Approved"
	// "05" -> "Do not honor"
	// "51" -> "Insufficient funds"
	// "54" -> "Expired card"
	// "55" -> "Incorrect PIN"
	// "91" -> "Issuer unavailable"
	//
	return "Unknown"
}

// MTI meaning helpers
func mtiVersionName(version int) string {
	switch version {
	case 0:
		return "ISO 8583:1987"
	case 1:
		return "ISO 8583:1993"
	case 2:
		return "ISO 8583:2003"
	default:
		return "Unknown"
	}
}

func mtiClassName(class int) string {
	switch class {
	case 1:
		return "Authorization"
	case 2:
		return "Financial"
	case 4:
		return "Reversal"
	case 8:
		return "Network Management"
	default:
		return "Unknown"
	}
}

func mtiFunctionName(function int) string {
	switch function {
	case 0:
		return "Request"
	case 1:
		return "Response"
	case 2:
		return "Advice"
	case 3:
		return "Advice Response"
	case 4:
		return "Notification"
	default:
		return "Unknown"
	}
}

func mtiOriginName(origin int) string {
	switch origin {
	case 0:
		return "Acquirer"
	case 1:
		return "Acquirer Repeat"
	case 2:
		return "Issuer"
	case 3:
		return "Issuer Repeat"
	case 4:
		return "Other"
	default:
		return "Unknown"
	}
}