Jimmy's Blog

Jimmy’s Blog – ISO 8583 Tutorial – Build and Parse ISO Message using JPOS library

by jimmy on Jul.26, 2011, under English, Java, Programming

ISO 8583 Tutorial article

In the beginning

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

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&lt;=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:

Create ISO packager based on the xml file.
Set the DE values. I use the previous article examples.
Print the DE values set.
Pack the message.
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&lt;=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:

Create ISO packager based on the xml file.
Set ISO Message.
Print the ISO Message.
Unpack the message.
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.

:8583, blog, build, iso, iso 8583, Java, jimmy, jpos, pack, packager, parse, Programming, tutorial, unpack

61 Comments for this entry

Alphonse
October 18th, 2011 on 1:03 pm
hello!,I like your writing very much! percentage we keep in touch more approximately your post on AOL? I require an expert in this house to resolve my problem. Maybe that’s you! Looking forward to look you.
pradnya
November 16th, 2011 on 1:08 pm
hello,
your article helps me alot to understand the iso 8583 format but i stuckd in problem during programme. it showing me that ISO packages you used there i m not able to find that. i am new in this field so please can u tell me how did u get that packages ISOEXception,Genericpackager ISOMsg.
Myat Thu
November 17th, 2011 on 5:26 pm
http://www.java2s.com/Code/Jar/j/Downloadjposjar.htm
jimmy
November 21st, 2011 on 12:05 am
@pradnya:
you can download JPOS at it website : http://www.jpos.org/
jimmy
November 21st, 2011 on 12:10 am
@Alphonse: just drop me some message at my pingbox or write you email address (I’ll remove it after I read it)
Aniket
December 2nd, 2011 on 4:12 pm
Thanks Jimmy ……….
Krishna
December 9th, 2011 on 4:13 am
Thanks.

Did clear some of the doubts. is JPOS free even for commercial use?
Pritesh
December 20th, 2011 on 3:05 am
Can you help me with what standard should I use in making a M-banking project , Is ISO 8583 suitable to be used in it..!
aniket.k.
December 20th, 2011 on 5:27 pm
I have included the jars and everything is working fine.But my only concern was do i need to worry about what happens under pack and unpack functions?
Krishna
December 20th, 2011 on 10:14 pm
Jimmy:

Greetings. I am only able to download the project from jpos.org.

Is there a way to download the jar files?

Thanks
Krishna
Krishna
December 20th, 2011 on 11:37 pm
@@aniket.k.:

How did you get the jar file? Did you build the project?

Than ks
Krishna
aniket
December 21st, 2011 on 12:10 pm
@krishna:
It is already given by Myat thu.
http://www.java2s.com/Code/Jar/j/Downloadjposjar.htm
jimmy
December 23rd, 2011 on 11:44 pm
Sorry I was a bit busy lately in my new company..

@Krishna:
If you go through the download page it will direct you to https://github.com/jpos/jPOS/tags
Based on the statement on the website, you’ll need to purchase commercial license.

@Pritesh:
I think JPOS is suitable for mbanking, although it’s not the only option I believe.

@Aniket:
What do you mean by under pack & unpack?
Krishna
December 23rd, 2011 on 11:56 pm
@Jimmy:
Thank you for this blogpost. I got the example to work in my computer.
I got the jPOS in maven in via git. And then did the maven compile and package and got the jar file. I was in the user forum for jPOS and they helped me with the compile.
My special thanks to you for getting me started through your blog.
Following are the steps suggested by one of users in the jpos-users@goolgegroups.com and I followed it and everything worked out. Got git installed in my computer (http://git-scm.com/) and added it to the PATH before proceeding with the following steps.Used JDK 1.6 Ver 30.
/*************************
Create a new directory with:
mkdir mynewdir
Then change to that directory:
cd mynewdir
You should now be in THAT directory, now type:
git clone https://github.com/jpos/jPOS.git
After a bit, you should have a pristine copy of the jPOS repository in that directory.
You can now type:
mvn compile
mvn package
************************************/

And then used your code and got it to work. I had to get the other libraries such as JDOM.

Thanks a lot.
Please keep up the good work.

Krishna
aniket
December 25th, 2011 on 3:34 am
@jimmy:As we can see IsoMsg class has two methods pack and unpack.So while creating any MTI,bitmap do i need to worry about what goes under these two methods?and can u tell me more about subfields may be sample just like one above?
Pritesh
December 26th, 2011 on 12:10 am
Jimmy:
Thanks for the reply. I am looking forward to use this in an android application.
Thanks, for the blogpost and all the resources. this has really been a great help..!!

Thanks a lot.
Manoj
January 19th, 2012 on 10:50 pm
Hi Jimmy,
Great post. I need to build ISO 8583 part of a project. You made it look so simple. Thanks again for helping out!
Omkar
February 9th, 2012 on 9:07 pm
Hi jimmy,

Your post really helpful for us.I used it in my code.But i am getting error while unpacking the data with subfields.
E.g. In my DE 114,i have used subfields. Subfield 3 is name.
While packing it does not give any error. But while unpacking,it gives error like below–>
org.jpos.iso.IFB_LLLBINARY: Problem unpacking field 0 (java.lang.ArrayIndexOutOfBoundsException) unpacking field=114, consumed=36

Can you please guide what might be the problem here?

Thanks
jimmy
February 9th, 2012 on 9:50 pm
I’ve been busy so sorry for my late replies.

@aniket:
As long you have configure packager (xml) correctly, we can assume the pack & unpack work properly.

@Omkar:
Can you post the data string, print out it before unpack it. And the xml (especially about DE-114)
From the error it seems the data is to short, so it’s throwing index out of bound when try to read DE-114
Omkar
February 10th, 2012 on 7:47 pm
Edwin
April 5th, 2012 on 2:13 am
Hi!
I am using this example it worked so fine. But now when I try to use for my own example I get this error:
Exception in thread "main" java.lang.NullPointerException at org.jpos.iso.ISOBasePackager.pack(ISOBasePackager.java:102) at org.jpos.iso.ISOMsg.pack(ISOMsg.java:333) at gnu.quijada.Iso8583.MyISOMSG.main(MyISOMSG.java:64)

i did my own basic.xml with my fields, i use this template

ISO 8583 0200 S
F2 Primary Acc. Num 5422********6290
F3 Processing Code 003000
F4 Amount of Transaction 125.00
F11 System Trace 000081
F14 Expiration date 1109
F18 Merchant Category 5411
F22 POS Entry Mode 012
F24 Network International ID 006
F25 POS condition code 08
F41 Terminal ID 12776859
F42 Card acceptor or Merchant # 349000000000
F49 Transaction Currency code 214
F62 Invoice/ECR Ref # 000001

We can use the same basic.xml for parse and build the message ?
I use the same xml but I added all fields that I need for both messages ?

I need to create different xml ?

The bitmap field is mandatory ?
This message doesnt use bitmap .

Thks for you help!!
SO good tutorial!!!
\
Edwin
April 5th, 2012 on 3:02 am
Answer myself….The XML basic needs the definition of field 1 for bitmap even you dont need it!!!

I add the field 1, bitmap, and this eliminated the error

Thks!!
Edwin
April 5th, 2012 on 5:05 am
Hi!
Another question JPOS can use BCD packet for send the message ?

The message to my gateway is using BCD
Sanjay
April 5th, 2012 on 1:55 pm
Hi Jimmy… amazing article.. i am very new to iso8583. following your tutorial… i am trying to write balance inquiry for some account number… so i do like this,

I am also reading some jpos documentation to set those fields…

isoMsg.setMTI(”0100″);
isoMsg.setPackager(packager);
isoMsg.set(2, “0000209″);
isoMsg.set(3, “3010″); // (30 – bal inquiry 10 – savings)

i am not sure if i did correct or wrong.. let me know..
jimmy
April 8th, 2012 on 12:14 am
@Edwin:
I’m not sure about BCD with JPOS, do you have any particular reason why you want to send the data in BCD?

@Sanjay:
For balance inquiry you will need to decide :
- Account number (#2)
- Processing code (#3)
- PIN (#52)
So I think you just need to add #52
Some other non mandatory usually:
- Date/time (#7)
- STAN (#11)
- etc
Sanjay
April 9th, 2012 on 7:37 pm
thanks Jimmy…. again – would this jpos library work in android? coz i was trying and getting No Class found exception… org.apache.crimson.parser.XMLReaderImpl in loader dalvik.system.PathClassLoader … anybody got that too?
Edwin
April 9th, 2012 on 10:12 pm
Jimmy, the problem is that the gateway that I use need BCD packets.
Sanjay
April 10th, 2012 on 4:23 pm
i could make it work in Android… DVM will not have org.apache parser in it…. so i have used SAX parser to do the same job… so made it worked.. however i am trying to build the response for the request i have sent 01006000000000000000070000209003010 ….
Sanjay
April 11th, 2012 on 11:04 am
Jimmy, i have generated a response.. not sure if it is correct.. can you check once?
ISOMsg isoMsg = new ISOMsg();
isoMsg.setMTI(”0110″); // response
isoMsg.setPackager(packager);
isoMsg.set(4, amount);
01101000000000000000000000005000
Sanjay
April 11th, 2012 on 11:14 am
@Edwin – i was searching for your BCD stuff — i think you can send BCD in header.. there is a utility in JPOS called ISOUtil.str2bcd(header, false) .. you can have a look..
Sanjay
April 11th, 2012 on 6:28 pm
Please let me know the below info are sufficient enough for Balance Query request and response..

ISO 8583 Format for the Balance Query Request
—-ISO MESSAGE—–
MTI : 0100
Field-2 : 070116123456789
Field-3 : 301000
Field-11 : 000001
RESULT: 0100602000000000000015070116123456789301000000001

ISO 8583 Format for the Balance Query Successful Response
—-ISO MESSAGE—–
MTI : 0110
Field-2 : 070116123456789
Field-3 : 301000
Field-4 : 5000
Field-11 : 000001
Field-12 : 024100
Field-13 : 0411
Field-39 : 00
——————–
RESULT : 0110703800000200000015070116123456789301000000000005000000001024100041100
jimmy
April 15th, 2012 on 3:13 pm
@sanjay:
Looks good, all the mandatory fields are there. Just realized I forgot to mention #39 in my previous comment.
Cecil Millbern
April 16th, 2012 on 3:37 pm
Thank you for sharing superb informations. Your website is so cool. I’m impressed by the details that you’ve on this site. It reveals how nicely you perceive this subject. Bookmarked this website page, will come back for extra articles. You, my friend, ROCK! I found simply the info I already searched everywhere and just could not come across. What an ideal web site.
jaganreddy
May 26th, 2012 on 2:34 pm
Hi Jimmy,

Great article it is very use full…thanks for your article and can you put the entire code in your blog instead of independent code…

regards
Jagan Reddy.
jaganreddy
May 26th, 2012 on 2:36 pm
Hi Jimmy,

I mean for downloading the entire code as a single file.

Thanks for your time…

Regards
Jagan Reddy
Gaurav
June 11th, 2012 on 7:02 pm
0067 ISO123456789 0800 82200000000000000400000000000000 0516124927 000001 301…
Can anyone tell me what does 0067 specifies over here..
aji
June 18th, 2012 on 9:25 am
Hi jimmy,

Good article, but i need your advice here :
- How do i parse the sub data element ?
- do you have iso8583:2003 packager ?, or can i modify the xml packager v 1993/1987 ?

Regards,
aji
jimmy
June 25th, 2012 on 4:20 pm
@jaganreddy:
You can download it using git from bitbucket : https://bitbucket.org/jimmod/blog_iso8583_parser/changeset/43e0ad9628b7

@Gaurav:
I’m not sure but it seem the first 2 sections (0067 ISO123456789) not really following ISO8583 standard format, may it’s custom implementation?

@aji:
You mean with JPos? I’m was not using JPos for a while so I’m a bit forgot – need to refresh my memory first.
You can use the same xml, what important is you need to match the elements.
Neva
July 17th, 2012 on 11:06 pm
Hi Jimmy,
Thanks for the beginner’s tutorial. It’s a great introduction!
Just one thing in your bitmap sample. You say
“You can see that in this bitmap it explain that data element in the message is 1, 3, 4, 7, 11.”
You’re missing the 44, also in the complete bitmap.
sirismail
August 3rd, 2012 on 3:17 pm
Hello, jimmy thanks you for this post. but i have but a have a problem during execution. this is my error

—-ISO MESSAGE—–
MTI : 0200
Field-3 : 201234
Field-4 : 10000
Field-7 : 1107221830
Field-11 : 123456
Field-44 : A5DFGR
Field-105 : ABCDEFGHIJ 1234567890
——————–
Exception in thread “main” java.lang.ArrayIndexOutOfBoundsException: 1
at org.jpos.q2.Q2.getRevision(Q2.java:749)
at org.jpos.q2.Q2.getVersionString(Q2.java:521)
at org.jpos.util.Logger.log(Logger.java:79)
at org.jpos.iso.ISOBasePackager.pack(ISOBasePackager.java:175)
at org.jpos.iso.ISOMsg.pack(ISOMsg.java:405)
at build.main(build.java:49)

thanks in advance
jimmy
August 5th, 2012 on 7:04 pm
@sirismail: I think you need to check the xml u used, is it the same with above example?
sandy
August 6th, 2012 on 10:27 am
thanks Jimmy.
How much is the length of the bitmap in basic.xml?if i use 128 bitmap.
sirismail
August 6th, 2012 on 3:31 pm
@jimmy yes its the same, i change it by a complete xml file but i have always the same error
sampath
August 9th, 2012 on 4:34 pm
How do i get the value of BITMAP field .
Please request you to provide me the solution as soon as possible.

Regards,
Sampath.
Lee Adil
August 9th, 2012 on 9:04 pm
Exactly where do one sign up for this blog? Cannot locate your blog feed icon in the footer.
Dino
August 21st, 2012 on 5:54 pm
Hello jimmy,
How do I add to ISOMessage fields like 47 and 59?
For example the field 59has the following tags: DF20, DF0D, DF15, DF2E, DF11, DF18.
I think method set() isn’t good.
Can you give me an example of code?
Thanks in advance

Dino
Leo
October 19th, 2012 on 11:26 am
Hello jimmy, do you know the source code to parse the data to BER-TLV format?
Venkat
January 9th, 2013 on 7:51 pm
ClassNotFoundException: org.jpos.iso.IFA_NUMERIC

i am new to both java and iso..

also i am trying to start with your example

but i get this error:
ClassNotFoundException: org.jpos.iso.IFA_NUMERIC
when i try to run the program
Venkat
January 9th, 2013 on 7:51 pm
ClassNotFoundException: org.jpos.iso.IFA_NUMERIC

i am new to both java and iso..

also i am trying to start with your example

but i get this error:
ClassNotFoundException: org.jpos.iso.IFA_NUMERIC
when i try to run the program

Please Guide
Mihir
January 25th, 2013 on 7:24 pm
please tell me how to implement it on android.