**cardutil-java** is a Java port of the [cardutil](https://github.com/adelosa/cardutil) Python package for working with payment card systems, including command-line tools for working with Mastercard IPM files.



* **ISO8583 Message Parsing**: Parse and pack ISO8583 messages.

* **Mastercard IPM File Handling**: Read, write, and convert Mastercard IPM files (including 1014 blocking support).

* **CLI Tools**: Convert between IPM and CSV formats.

* **Cryptography Utilities**: Check digit calculator, Pin Block generator, Visa PVV calculator.

* **Zero Dependencies**: Core library relies only on standard Java libraries (except for CLI which uses `commons-csv`).

Add the JitPack repository to your `pom.xml`:

<repositories>

<repository>

<id>jitpack.io</id>

<url>https://jitpack.io</url>

</repository>

</repositories>

Add the dependency:

<dependency>

<groupId>com.github.charisad</groupId>

<artifactId>cardutil-java</artifactId>

<version>Tag</version>

</dependency>

import com.charisad.cardutil.Iso8583;

import java.util.Map;

byte[] messageBytes = ...;

Map<String, Object> data = Iso8583.unpack(messageBytes, null);

System.out.println("MTI: " + data.get("MTI"));

System.out.println("PAN: " + data.get("DE2"));

import com.charisad.cardutil.MciIpm;

import java.nio.file.Files;

import java.nio.file.Paths;

try (InputStream is = Files.newInputStream(Paths.get("incoming.ipm"));

MciIpm.IpmReader reader = new MciIpm.IpmReader(is, true)) { // true for 1014 blocking

for (Map<String, Object> record : reader) {

System.out.println(record);

}

}

The library includes a CLI for common tasks.

mvn exec:java -Dexec.mainClass="com.charisad.cardutil.Cli" -Dexec.args="ipm2csv input.ipm -o output.csv"

mvn exec:java -Dexec.mainClass="com.charisad.cardutil.Cli" -Dexec.args="csv2ipm input.csv -o output.ipm"

This project is a direct port of the Python [cardutil](https://github.com/adelosa/cardutil) library by Anthony Delosa.

* Original Author: [Anthony Delosa](https://github.com/adelosa)

* Original License: MIT

Ported and maintained by [charisad](https://github.com/charisad).

MIT

jdk:

- openjdk17

install:

- mvn clean install -DskipTests -Dmaven.javadoc.skip=true

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

<modelVersion>4.0.0</modelVersion>

<groupId>com.charisad</groupId>

<artifactId>cardutil</artifactId>

<packaging>jar</packaging>

<version>1.0-SNAPSHOT</version>

<name>cardutil</name>

<url>http://maven.apache.org</url>

<properties>

<maven.compiler.source>17</maven.compiler.source>

<maven.compiler.target>17</maven.compiler.target>

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

</properties>

<dependencies>

<dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter-api</artifactId>

<version>5.10.0</version>

<scope>test</scope>

</dependency>

<repositories>

<repository>

<id>jitpack.io</id>

<url>https://jitpack.io</url>

</repository>

</repositories>

<dependency>

<groupId>com.github.charisad</groupId>

<artifactId>cardutil</artifactId>

<version>1.0-SNAPSHOT</version>

</dependency>

<dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter-engine</artifactId>

<version>5.10.0</version>

<scope>test</scope>

</dependency>

<!-- SLF4J for logging, binding to simple logger for zero-config defaults -->

<dependency>

<groupId>org.slf4j</groupId>

<artifactId>slf4j-api</artifactId>

<version>2.0.9</version>

</dependency>

<dependency>

<groupId>org.slf4j</groupId>

<artifactId>slf4j-simple</artifactId>

<version>2.0.9</version>

</dependency>

<dependency>

<groupId>org.apache.commons</groupId>

<artifactId>commons-csv</artifactId>

<version>1.10.0</version>

</dependency>

</dependencies>

<build>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-source-plugin</artifactId>

<version>3.3.0</version>

<executions>

<execution>

<id>attach-sources</id>

<goals>

<goal>jar</goal>

</goals>

</execution>

</executions>

</plugin>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-javadoc-plugin</artifactId>

<version>3.6.3</version>

<executions>

<execution>

<id>attach-javadocs</id>

<goals>

<goal>jar</goal>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

package com.charisad.cardutil;

public record BitConfig(

String fieldName,

FieldType fieldType,

int fieldLength,

String fieldProcessor,

String fieldProcessorConfig,

String fieldJavaType,

String fieldDateFormat

) {

public enum FieldType {

FIXED, LLVAR, LLLVAR

}

public static Builder builder() {

return new Builder();

}

public static class Builder {

private String fieldName;

private FieldType fieldType;

private int fieldLength;

private String fieldProcessor;

private String fieldProcessorConfig;

private String fieldJavaType;

private String fieldDateFormat;

public Builder fieldName(String fieldName) { this.fieldName = fieldName; return this; }

public Builder fieldType(FieldType fieldType) { this.fieldType = fieldType; return this; }

public Builder fieldLength(int fieldLength) { this.fieldLength = fieldLength; return this; }

public Builder fieldProcessor(String fieldProcessor) { this.fieldProcessor = fieldProcessor; return this; }

public Builder fieldProcessorConfig(String fieldProcessorConfig) { this.fieldProcessorConfig = fieldProcessorConfig; return this; }

public Builder fieldJavaType(String fieldJavaType) { this.fieldJavaType = fieldJavaType; return this; }

public Builder fieldDateFormat(String fieldDateFormat) { this.fieldDateFormat = fieldDateFormat; return this; }

public BitConfig build() {

return new BitConfig(fieldName, fieldType, fieldLength, fieldProcessor, fieldProcessorConfig, fieldJavaType, fieldDateFormat);

}

}

}

package com.charisad.cardutil;

import java.util.BitSet;

public class BitUtils {

/**

public static BitSet fromBytes(byte[] bytes) {

BitSet bits = new BitSet(bytes.length * 8);

for (int i = 0; i < bytes.length * 8; i++) {

if ((bytes[i / 8] & (1 << (7 - (i % 8)))) > 0) {

bits.set(i);

}

}

return bits;

}

/**

public static byte[] toBytes(BitSet bits, int lengthBytes) {

byte[] bytes = new byte[lengthBytes];

for (int i = 0; i < lengthBytes * 8; i++) {

if (bits.get(i)) {

bytes[i / 8] |= (1 << (7 - (i % 8)));

}

}

return bytes;

}

}

package com.charisad.cardutil;

public class Card {

/**

public static String calculateCheckDigit(String cardNumber) {

// Python: digits = [int(digit) for digit in card_number if digit.isdigit()]

// total = sum([sum(divmod(multiplier * digit, 10)) for digit, multiplier in zip(digits[::-1], cycle([2, 1]))])

// return str((total * 9) % 10)

int sum = 0;

boolean alternate = true;

for (int i = cardNumber.length() - 1; i >= 0; i--) {

int n = Character.getNumericValue(cardNumber.charAt(i));

if (alternate) {

n *= 2;

if (n > 9) {

n = (n % 10) + 1;

}

}

sum += n;

alternate = !alternate;

}

return String.valueOf((sum * 9) % 10);

}

public static boolean validateCheckDigit(String cardNumber) {

if (cardNumber == null || cardNumber.length() < 2) return false;

String number = cardNumber.substring(0, cardNumber.length() - 1);

String checkDigit = cardNumber.substring(cardNumber.length() - 1);

return calculateCheckDigit(number).equals(checkDigit);

}

public static String addCheckDigit(String cardNumber) {

return cardNumber + calculateCheckDigit(cardNumber);

}

public static String mask(String cardNumber) {

return mask(cardNumber, '*');

}

public static String mask(String cardNumber, char maskChar) {

if (cardNumber == null || cardNumber.length() <= 10) return cardNumber;

// First 6, last 4

StringBuilder sb = new StringBuilder();

sb.append(cardNumber.substring(0, 6));

for (int i = 0; i < cardNumber.length() - 10; i++) {

sb.append(maskChar);

}

sb.append(cardNumber.substring(cardNumber.length() - 4));

return sb.toString();

}

}

package com.charisad.cardutil;

public class CardutilError extends RuntimeException {

public CardutilError(String message) {

super(message);

}

public CardutilError(String message, Throwable cause) {

super(message, cause);

}

}