Moov ISO8583

When working with composite fields (like BER-TLV), you may encounter tags not defined in your specification. The library allows you to skip or store these tags.

Skipping Unknown Tags

Set SkipUnknownTLVTags: true in the TagSpec of the composite field.

• BER-TLV: Works automatically; the parser reads the tag and length.
• Non-BER TLV: Requires PrefUnknownTLV to be set so the parser knows how to read the length of unknown tags.

Storing Unknown Tags

To preserve unknown tags (e.g., for re-packing the message intact), set StoreUnknownTLVTags: true in the TagSpec. Unknown tags are stored as Binary fields inside the composite.

Retrieving Stored Unknown Tags

Use iso8583.UnknownTags(msg) to get a map of unknown fields keyed by their dot-separated path (e.g., "55.9F36"). For standalone composite fields, use iso8583.UnknownCompositeTags(composite).

// Example: Configuring a TagSpec to skip and store unknown tags
Tag: &field.TagSpec{
    Enc:                 encoding.BerTLVTag,
    Sort:                sort.StringsByHex,
    SkipUnknownTLVTags:  true,
    StoreUnknownTLVTags: true,
},

// Retrieving unknown tags after Unpack
unknownTags := iso8583.UnknownTags(msg)
for path, f := range unknownTags {
    val, _ := f.Bytes()
    fmt.Printf("Unknown tag at %s: %X\n", path, val)
}

An ISO 8583 message begins with a four-digit Message Type Indicator (MTI). Each digit provides specific metadata about the transaction:

1. First Digit (Version): Specifies the ISO 8583 version (e.g., 0 for 1987, 1 for 1993, 2 for 2003).
2. Second Digit (Message Class): Defines the purpose of the message (e.g., 1 for Authorization, 2 for Financial).
3. Third Digit (Message Function): Defines the message flow (e.g., 0 for Request, 1 for Request Response, 2 for Advice).
4. Fourth Digit (Message Origin): Indicates the source in the payment chain (e.g., 0 for Acquirer, 2 for Issuer).

By combining these digits, you can fully describe the transaction type, version, and direction.

Example: MTI `1100`
- Digit 1: `1` (ISO 8583:1993)
- Digit 2: `1` (Authorization)
- Digit 3: `0` (Request)
- Digit 4: `0` (Acquirer)
Result: An authorization request originating from the acquirer using the 1993 version.

When working with complex composite fields, isolate testing by defining and testing the field.Spec for the composite field independently of the full message.

Follow this workflow for testing:

1. Define the field.Spec for the composite field.
2. Create the field instance using field.NewComposite(spec).
3. Define a test data struct with index tags matching the subfield IDs.
4. Marshal: Convert the struct to the field's internal representation using composite.Marshal(data).
5. Pack: Convert the field to raw binary using composite.Pack().
6. Unpack: Convert raw binary back to a field instance using unpackedField.Unpack(packed).
7. Unmarshal: Convert the field instance back into a Go struct using unpackedField.Unmarshal(unpacked).

func TestDataSetCompositeField(t *testing.T) {
	spec := &field.Spec{
		// ... spec definition
	}
	composite := field.NewComposite(spec)

	data := &TestData{
		MerchantData: &MerchantData{
			MerchantID: field.NewStringValue("12345ABCDE"),
		},
	}

	// 1. Marshal
	err := composite.Marshal(data)
	require.NoError(t, err)

	// 2. Pack
	packed, err := composite.Pack()
	require.NoError(t, err)

	// 3. Unpack
	unpackedField := field.NewComposite(spec)
	read, err := unpackedField.Unpack(packed)
	require.NoError(t, err)

	// 4. Unmarshal
	unpacked := &TestData{}
	err = unpackedField.Unmarshal(unpacked)
	require.NoError(t, err)

	// Verify
	require.Equal(t, "12345ABCDE", unpacked.MerchantData.MerchantID.Value())
}

This example demonstrates the full lifecycle of an ISO 8583 message: defining a message structure using Go structs with iso8583 tags, packing a message for transmission, and unpacking/parsing a received message.

Key steps include:

1. Defining structs with iso8583 tags mapping to field numbers.
2. Using iso8583.NewMessage(spec) to initialize a message with a specific specification.
3. Using msg.Marshal(data) to populate the message from a struct.
4. Using msg.Pack() to convert the message into its wire format.
5. Using msg.Unpack(packed) to parse wire data back into a message object.
6. Using msg.UnmarshalPath(path, &target) to extract specific fields or subfields (e.g., 43.1).
7. Using msg.Unmarshal(target) to populate a struct from the message.

package main

import (
	"fmt"
	"os"

	"github.com/moov-io/iso8583"
	"github.com/moov-io/iso8583/examples"
)

// Define types for the message fields
type Authorization struct {
	MTI                  string               `iso8583:"0"`  // Message Type Indicator
	PrimaryAccountNumber string               `iso8583:"2"`  // PAN
	ProcessingCode       string               `iso8583:"3"`  // Processing code
	Amount               int64                `iso8583:"4"`  // Transaction amount
	STAN                 string               `iso8583:"11"` // System Trace Audit Number
	ExpirationDate       string               `iso8583:"14"` // YYMM
	AcceptorInformation  *AcceptorInformation `iso8583:"43"` // Merchant details
}

type AcceptorInformation struct {
	Name    string `iso8583:"1"`
	City    string `iso8583:"2"`
	Country string `iso8583:"3"`
}

func main() {
	// Pack the message
	msg := iso8583.NewMessage(examples.Spec)

	authData := &Authorization{
		MTI:                  "0100",
		PrimaryAccountNumber: "4242424242424242",
		ProcessingCode:       "000000",
		Amount:               2599,
		ExpirationDate:       "2201",
		AcceptorInformation: &AcceptorInformation{
			Name:    "Merchant Name",
			City:    "Denver",
			Country: "US",
		},
	}

	// Set the field values
	err := msg.Marshal(authData)
	if err != nil {
		panic(err)
	}

	// Pack the message
	packed, err := msg.Pack()
	if err != nil {
		panic(err)
	}

	// send packed message to the server
	// ...

	// Unpack the message
	msg = iso8583.NewMessage(examples.Spec)
	err = msg.Unpack(packed)
	if err != nil {
		panic(err)
	}

	// get individual field values
	var amount int64
	err = msg.UnmarshalPath("4", &amount)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Amount: %d\n", amount)

	// get value of composite subfield
	var acceptorName string
	err = msg.UnmarshalPath("43.1", &acceptorName)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Acceptor Name: %s\n", acceptorName)

	// Get the field values into data structure
	authData = &Authorization{}
	err = msg.Unmarshal(authData)
	if err != nil {
		panic(err)
	}

	// Print the entire message
	iso8583.Describe(msg, os.Stdout)
}