ISO 8583 Tutorial article

• Introduction for Beginners
• Build and Parse ISO Message using JPOS library
• ????

In the beginning

OK after my article about ISO 8583 let’s go deeper into programming using Java + JPOS library.

Quote from JPOS website:

jPOS is a Java® platform-based, mission-critical, ISO-8583 based financial transaction library/framework that can be customized and extended in order to implement financial interchanges.

So first thing to do is download JPOS from it website.

Then we setup our development environment by creating Java Project using your favorites IDE. Add to the project all jar in JPOS library.
Here’s my Eclipse  package explorer looks like.

package explorer

Create Data Elements (DE) types XML

Like I said that ISO 8583 is a ’standard’ which mean can be different between one implementation and another
To put it simple, although there’s a (some) standard for DE list sometime we need to change it.
Either way, we need to tell JPOS how our DE will be formatted or packaged.

Since in the complete XML there’s 128 DE, I’ll quote only the DE # we used. Full xml can be downloaded here (basic.xml)

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE isopackager SYSTEM "genericpackager.dtd">
<isopackager>
  <isofield
      id="0"
      length="4"
      name="MESSAGE TYPE INDICATOR"
      class="org.jpos.iso.IFA_NUMERIC"/>
  <isofield
      id="1"
      length="64"
      name="BIT MAP"
      class="org.jpos.iso.IFA_BITMAP"/>
  <isofield
      id="3"
      length="6"
      name="PROCESSING CODE"
      class="org.jpos.iso.IFA_NUMERIC"/>
  <isofield
      id="4"
      length="12"
      name="AMOUNT, TRANSACTION"
      class="org.jpos.iso.IFA_NUMERIC"/>
  <isofield
      id="7"
      length="10"
      name="TRANSMISSION DATE AND TIME"
      class="org.jpos.iso.IFA_NUMERIC"/>
  <isofield
      id="11"
      length="6"
      name="SYSTEM TRACE AUDIT NUMBER"
      class="org.jpos.iso.IFA_NUMERIC"/>
  <isofield
      id="44"
      length="25"
      name="ADITIONAL RESPONSE DATA"
      class="org.jpos.iso.IFA_LLCHAR"/>
  <isofield
      id="105"
      length="999"
      name="RESERVED ISO USE"
      class="org.jpos.iso.IFA_LLLCHAR"/>
</isopackager>

The XML should easily understand in each isofield tag we define:

• id : the DE number
• length : the max/fixed length of the DE
• name : yes, it’s the name or description
• class : this define the type of the DE, which in this case represent by the JPOS class. You can see the whole class list here. I only list some of it.
  • IFA_NUMERIC : Numeric – Left padder with zeros.
  • IFA_BITMAP : For ISO Bitmap
  • IFA_LLCHAR : ASCII variable len CHAR – 2 digit length info
  • IFA_LLLCHAR : ASCII variable len CHAR – 3 digit length info

So this XML will be used for build (pack) ISO Message or parse (unpack) ISO Message.

You will need the XML data schema (genericpackager.dtd) to be put on same directory with basic.xml

Build (pack) ISO Message

Below is the code. The code is quite straight forward, review it first and I’ll discuss a bit afterward.

package gnu.jimmod.iso8583.utility;
 
import java.io.IOException;
import org.jpos.iso.ISOException;
import org.jpos.iso.ISOMsg;
import org.jpos.iso.packager.GenericPackager;
 
public class BuildISOMessage {
 
	public static void main(String[] args) throws IOException, ISOException {
		// Create Packager based on XML that contain DE type
		GenericPackager packager = new GenericPackager("basic.xml");
 
		// Create ISO Message
		ISOMsg isoMsg = new ISOMsg();
		isoMsg.setPackager(packager);
		isoMsg.setMTI("0200");
		isoMsg.set(3, "201234");
		isoMsg.set(4, "10000");
		isoMsg.set(7, "110722180");
		isoMsg.set(11, "123456");
		isoMsg.set(44, "A5DFGR");
		isoMsg.set(105, "ABCDEFGHIJ 1234567890");
 
		// print the DE list
		logISOMsg(isoMsg);
 
		// Get and print the output result
		byte[] data = isoMsg.pack();
		System.out.println("RESULT : " + new String(data));
	}
 
	private static void logISOMsg(ISOMsg msg) {
		System.out.println("----ISO MESSAGE-----");
		try {
			System.out.println("  MTI : " + msg.getMTI());
			for (int i=1;i<=msg.getMaxField();i++) {
				if (msg.hasField(i)) {
					System.out.println("    Field-"+i+" : "+msg.getString(i));
				}
			}
		} catch (ISOException e) {
			e.printStackTrace();
		} finally {
			System.out.println("--------------------");
		}
 
	}
 
}

The output:

----ISO MESSAGE-----
  MTI : 0200
    Field-3 : 201234
    Field-4 : 10000
    Field-7 : 110722180
    Field-11 : 123456
    Field-44 : A5DFGR
    Field-105 : ABCDEFGHIJ 1234567890
--------------------
RESULT : 0200B2200000001000000000000000800000201234000000010000011072218012345606A5DFGR021ABCDEFGHIJ 1234567890

The program flow:

1. Create ISO packager based on the xml file.
2. Set the DE values. I use the previous article examples.
3. Print the DE values set.
4. Pack the message.
5. Print the formatted ISO message. As you can see the result is the same with the previous article examples.

Parse (unpack) ISO Message

On this case it’s reversed. We have the ISO Message, and we need to see the DE values of it.
Like the previous code this one also similar and should be easy to understand.

package gnu.jimmod.iso8583.utility;
 
import java.io.IOException;
import org.jpos.iso.ISOException;
import org.jpos.iso.ISOMsg;
import org.jpos.iso.packager.GenericPackager;
 
public class ParseISOMessage {
 
	public static void main(String[] args) throws IOException, ISOException {
		// Create Packager based on XML that contain DE type
		GenericPackager packager = new GenericPackager("basic.xml");
 
		// Print Input Data
		String data = "0200B2200000001000000000000000800000201234000000010000011072218012345606A5DFGR021ABCDEFGHIJ 1234567890";
		System.out.println("DATA : " + data);
 
		// Create ISO Message
		ISOMsg isoMsg = new ISOMsg();
		isoMsg.setPackager(packager);
		isoMsg.unpack(data.getBytes());
 
		// print the DE list
		logISOMsg(isoMsg);
	}
 
	private static void logISOMsg(ISOMsg msg) {
		System.out.println("----ISO MESSAGE-----");
		try {
			System.out.println("  MTI : " + msg.getMTI());
			for (int i=1;i<=msg.getMaxField();i++) {
				if (msg.hasField(i)) {
					System.out.println("    Field-"+i+" : "+msg.getString(i));
				}
			}
		} catch (ISOException e) {
			e.printStackTrace();
		} finally {
			System.out.println("--------------------");
		}
 
	}
 
}

The output:

DATA : 0200B2200000001000000000000000800000201234000000010000011072218012345606A5DFGR021ABCDEFGHIJ 1234567890
----ISO MESSAGE-----
  MTI : 0200
    Field-3 : 201234
    Field-4 : 000000010000
    Field-7 : 0110722180
    Field-11 : 123456
    Field-44 : A5DFGR
    Field-105 : ABCDEFGHIJ 1234567890
--------------------

The program flow:

1. Create ISO packager based on the xml file.
2. Set ISO Message.
3. Print the ISO Message.
4. Unpack the message.
5. Print the DE values. As you can see the result is correct, just like the DE set in first example.

In the end

Ok, like always I hope I make it clear for you.
This might not (yet) a tutorial to make you able the whole financial platform or a bank platform
But everyone need to start somewhere.

I see this code example as the implementation of my previous article (ISO 8583 introduction)

Just leave comment if you have questions.

Related posts:

1. Jimmy’s Blog – ISO 8583 Tutorial – Introduction for Beginners
2. Simple Log4J implementation
3. Java ME (J2ME) JSON Implementation Tutorial/Sample

ISO 8583 Tutorial article

• Introduction for Beginners
• Build and Parse ISO Message using JPOS library
• ????

Introduction

Lately I’ve handle several financial project that allow me to understand bank and financial transaction better.
All (or most?) financial transaction is using ISO 8583 standard, which at first I thought is a complicated standard. But after learn and see how it implemented it’s not as complex as I thought.
In this post I will try to explain (based on my experience before I go deeper on the programming side.

Although it’s a ’standard’ I see that’s many variant for the detail implementation of ISO 8583.

Financial transaction is communication between 2 system through socket connection.
After connection established, each system can send message in ISO 8583 format which commonly will be request and the other system will response.
From my experience the communication will be start with sign on and then the financial transactions.
Periodically an echo message is send to make sure the other system is still alive.

If I break down the flow:

1. System A open connection to System B (through specific IP and Port).
2. Connection established.
3. System A send Sign-On request message.
4. System B send Sign-on response message.
5. System A will start send Echo request message periodically (e.g every 1 minute).
6. System B will send Echo response message when receive Echo request message.
7. When financial transaction happen, System A will send Transaction request message.
8. Then System B will send Transaction response message.
9. If something wrong happen (usually timeout so System A didn’t get the response), System A will send Reversal request message to cancel the previous transaction.
10. System B will send Reversal response message.

I hope my explaination give clear basic understanding about the flow.
Next the question will be what’s this ISO 8583 message looks like.
We can separate the message into 3 parts:

• Message Type Identifier
• Bitmaps
• Data Elements

ISO8583 - structure

Message Type Identifier

Message Type Identifier or MTI is 4 digits numeric that describe the message type. It will explain the message function.
Commonly used:
- 02xx : Financial Message (e.g 0200 for request, 0210 for response)
- 04xx : Reversal Message (e.g 0400 for request, 0410 for response)
- 08xx : Network Management Message (e.g 0800 for request, 0810 for response)
* I found more detail & complete list at wikipedia

Bitmaps

Bitmaps is field that contain information about which data element is presence or absence. Based on the variant it could be 16 hexadecimal characters.
An example will make it clear.

The bitmap is:

B220000000100000

If we break down to binary (I hope you understand how to convert hexadecimal to binary:) :

1011001000100000000000000000000000000000000100000000000000000000

Since I’m nice I create graphical illustration.

Bitmap sample

You can see that in this bitmap it explain that data element in the message is 1, 3, 4, 7, 11.
There’s special meaning of first bit of bitmap, if it has value of 1 that mean there’s secondary bitmap.
And what the hell is this secondary bitmap?
Since 16 hexadecimal characters will can only contain info of 64 data element, some transactions contain data element number 64 – 128. That mean the 16 hexadecimal characters is not sufficient.
With set the first bit to ‘1′ that will inform there’s additional bitmap, which is another 16 hexadecimal characters.
So in this case the full bitmap example should be:
B2200000001000000000000000800000
Convert to binary:
10110010001000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000100000000000000000000000
From the bitmap, data element presence in the message : 3, 4, 7, 11, 105.

Sample Bitmap complete

Data Elements

Data Elements is the essense of the whole ISO message, contain information about the transaction (transaction type, amount, customer id, etc).
Each data element have their on format, attribute and length.
Each data element number also have standard purpose, for example DE #4 is transaction amount.
I will explain based on the example above, since this is only introduction I don’t want to confuse beginner reader. In wikipedia there’s full list.
For our examples, the data element list:

• #3 – Processing code – n 6
• #4 – Transaction amount – n 12
• #7 – Transmission date & time – n 10
• #11 – Systems trace audit number – n 6
• #44 – Additional response data – an ..25
• #105 – Reserved for ISO use – ans …999

To make it practical let’s just use example.
We want to send :

• DE #3 : 201234
• DE #4 : 10000
• DE #7 : 1107221830
• DE #11 : 123456
• DE #44 : A5DFGR
• DE #105 : ABCDEFGHIJ 1234567890

Using above value, the data in data elements :

ISO8583 - de

Based on the type each value will be formatted.

• a : alpha (including blanks)
• n : numeric value
• s : special characters
• x (no dot) : length is x (fixed)
• .x (one dot) :  max length is x (1 digit in front as length info)
• ..xx (two dot) :  max length is xx (2 digit in front as length info)
• …xxx (three dot) :  max length is xxx (3 digit in front as length info)

ISO Message

From above examples the whole ISO message will be :

0200B2200000001000000000000000800000201234000000010000110722183012345606A5DFGR021ABCDEFGHIJ 1234567890

Conclusion

Ok. This article already long enough
Actually I always prefer short article, but on this case it’s cannot be to short.
Anyway, I hope this article is clear enough for you.

Like always, just drop question in the comment if you confused.

Next I will write article about implementing ISO 8583 using JPOS library.

Related posts:

1. Jimmy’s Blog – ISO 8583 Tutorial – Build and Parse ISO Message using JPOS library
2. Basic LWUIT tutorial/sample with Eclipse Pulsar
3. Jimmy’s Blog – Send & Receiving SMS on specific Port with J2ME Application

Okay, finally you decide it’s time to create a unit testing for your project (after a long ad hoc programming life :p).
When you create a sample unit testing, it’s all seem so simple.. you fascinate by the junit easiness, how it can do reflection and make it simple.

When you want to create a real unit testing for your project, you realize that a ‘real’ method is not like just adding 2 int argument and return a result. It’s more complex and using interface as parameter is common…
Now a thought cross your mind “do I have to create all stupid classes to implement all the interface I need?”, you starting to think that creating unit testing is really waste of time & you don’t want to do it anymore :p

It’s time mock object framework come to rescue… before you fall to the darkness of untested code
There’re several mock object framework like jMock, easymock, etc

Here’s an example creatin HttpMethod mock-object with jMock 2 & JUnit 3

[sourcecode language='java']
public class sampleJMockTest extends MockObjectTestCase {
public void testCreateHTTPMethod() {
final HttpMethod httpMethod = mock(HttpMethod.class);
checking(new Expectations() {
{
allowing(httpMethod).getResponseBodyAsString();
will(returnValue(”sample response”));
}
});
SomeObject someObject = new SomeObject();
someObject.someMethod(httpMethod);
}
}[/sourcecode]
This sample will create an instance of HttpMethod (which is an interface) and when this mock object’s ‘getResponseBodyAsString’ method called it’ll return “sample response”.
So now we can easily create all interface implementation we need.Of course there’re more in jMock than just this simple feature, check it more at jMock Cookbook

Related posts:

1. Java ME (J2ME) JSON Implementation For Array Object
2. Java – Adding new Classpath at Runtime
3. Java ME (J2ME) JSON Implementation Tutorial/Sample