3.md

3. Data Elements

Data elements are the building blocks of ISO-8583 messages. They contain specific pieces of information required for processing financial transactions.

3.1. Mandatory vs. Optional fields

3.1.1. Identifying mandatory fields

Mandatory fields are essential for processing a transaction and must be included in every message. These fields are typically defined by the message type and the specific requirements of the card network (Visa or Mastercard).

Example of common mandatory fields:

• Message Type Indicator (MTI)
• Primary Account Number (PAN)
• Processing Code
• Transaction Amount

3.1.2. Handling optional fields

Optional fields provide additional information that may be required for specific transaction types or to support certain features. These fields can be omitted if not needed.

Example of handling optional fields in Java using jPOS:

import org.jpos.iso.ISOMsg;
import org.jpos.iso.ISOException;

public class OptionalFieldHandler {
    public void handleOptionalField(ISOMsg msg, int fieldNumber) {
        try {
            if (msg.hasField(fieldNumber)) {
                String value = msg.getString(fieldNumber);
                // Process the optional field
                System.out.println("Optional field " + fieldNumber + " present: " + value);
            } else {
                System.out.println("Optional field " + fieldNumber + " not present");
            }
        } catch (ISOException e) {
            e.printStackTrace();
        }
    }
}

3.2. Fixed-length vs. Variable-length fields

3.2.1. Length indicators for variable fields

Variable-length fields are preceded by a length indicator, which specifies the number of characters in the field. The length indicator itself can be of fixed length (e.g., 2 or 3 digits).

Example of a variable-length field structure:

[Length Indicator][Field Value]

For instance, if field 43 (Card Acceptor Name/Location) contains "ACME Store 123 Main St", it might be represented as:

019ACME Store 123 Main St

Here, "019" is the length indicator, showing that the field value is 19 characters long.

3.2.2. Padding for fixed-length fields

Fixed-length fields always occupy the same number of characters. If the actual data is shorter than the specified length, it is padded with a filler character (often spaces or zeros).

Example of padding a fixed-length field in Java:

public class FixedLengthFieldPadder {
    public String padField(String value, int length, char paddingChar) {
        if (value == null) {
            value = "";
        }
        if (value.length() > length) {
            return value.substring(0, length);
        }
        StringBuilder sb = new StringBuilder(length);
        sb.append(value);
        while (sb.length() < length) {
            sb.append(paddingChar);
        }
        return sb.toString();
    }
}

3.3. Key data elements for Visa and Mastercard transactions

Let's go through some of the most important data elements used in Visa and Mastercard transactions:

3.3.1. Primary Account Number (PAN)

• Field number: 2
• Description: The card number
• Format: n..19 (variable length numeric, up to 19 digits)

3.3.2. Processing Code

• Field number: 3
• Description: Indicates the type of transaction (e.g., purchase, cash advance)
• Format: n6 (fixed length, 6 digits)

3.3.3. Transaction Amount

• Field number: 4
• Description: The amount of the transaction
• Format: n12 (fixed length, 12 digits)

3.3.4. Transmission Date and Time

• Field number: 7
• Description: Date and time the message was sent
• Format: n10 (MMDDhhmmss)

3.3.5. Systems Trace Audit Number (STAN)

• Field number: 11
• Description: Unique transaction identifier assigned by the sender
• Format: n6

3.3.6. Time, Local Transaction

• Field number: 12
• Description: Time of the transaction at the point of service
• Format: n6 (hhmmss)

3.3.7. Date, Local Transaction

• Field number: 13
• Description: Date of the transaction at the point of service
• Format: n4 (MMDD)

3.3.8. Date, Expiration

• Field number: 14
• Description: Expiration date of the card
• Format: n4 (YYMM)

3.3.9. Merchant Type

• Field number: 18
• Description: Classifies the type of business
• Format: n4

3.3.10. Acquiring Institution ID Code

• Field number: 32
• Description: Identifies the acquirer
• Format: n..11

3.3.11. Track 2 Data

• Field number: 35
• Description: Data from the magnetic stripe
• Format: z..37

3.3.12. Retrieval Reference Number

• Field number: 37
• Description: Unique transaction identifier assigned by the acquirer
• Format: an12

3.3.13. Authorization ID Response

• Field number: 38
• Description: Approval code from the issuer
• Format: an6

3.3.14. Response Code

• Field number: 39
• Description: Indicates the result of the transaction request
• Format: an2

3.3.15. Card Acceptor Terminal ID

• Field number: 41
• Description: Identifies the specific terminal
• Format: ans8

3.3.16. Card Acceptor ID Code

• Field number: 42
• Description: Identifies the merchant
• Format: ans15

3.3.17. Card Acceptor Name/Location

• Field number: 43
• Description: Name and location of the merchant
• Format: ans..40

3.3.18. Additional Data - Private

• Field number: 48
• Description: Used for additional data specific to the card network or acquirer
• Format: ans..999

3.4. Data types and formats

ISO-8583 uses several data types to represent field values:

3.4.1. Numeric (n)

• Contains only digits (0-9)
• Example: Transaction Amount (n12)

3.4.2. Alphabetic (a)

• Contains only letters (A-Z, a-z)
• Rarely used alone in ISO-8583

3.4.3. Special (s)

• Contains special characters (e.g., punctuation)
• Often combined with other types

3.4.4. Alphanumeric (an)

• Contains letters and digits
• Example: Retrieval Reference Number (an12)

3.4.5. Binary (b)

• Contains binary data
• Example: Bitmap (b64)

3.4.6. Track 2 (z)

• Special format for magnetic stripe data
• Example: Track 2 Data (z..37)

Here's a Java example demonstrating how to handle different data types in jPOS:

import org.jpos.iso.ISOMsg;
import org.jpos.iso.ISOException;
import org.jpos.iso.ISOUtil;

public class DataTypeHandler {
    public void handleDataTypes(ISOMsg msg) throws ISOException {
        // Numeric
        String amount = msg.getString(4);
        long amountValue = Long.parseLong(amount);

        // Alphanumeric
        String rrn = msg.getString(37);

        // Binary
        byte[] binaryData = msg.getBytes(53);

        // Track 2
        String track2 = msg.getString(35);
        String pan = track2.split("=")[0];
        String expirationDate = track2.split("=")[1].substring(0, 4);

        // Special handling for date/time fields
        String transmissionDateTime = msg.getString(7);
        String formattedDateTime = ISOUtil.formatDate(transmissionDateTime, "MMddHHmmss");

        System.out.println("Amount: " + amountValue);
        System.out.println("RRN: " + rrn);
        System.out.println("Binary Data Length: " + binaryData.length);
        System.out.println("PAN from Track 2: " + pan);
        System.out.println("Expiration Date from Track 2: " + expirationDate);
        System.out.println("Formatted Transmission Date/Time: " + formattedDateTime);
    }
}