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

[Switch to Mobile Edition]

ISO 8583 Tutorial article

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

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 :D
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:

  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&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:

  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. Java ME (J2ME) JSON Implementation Tutorial/Sample
  3. Simple Log4J implementation
  4. Jimmy’s Blog – Send & Receiving SMS on specific Port with J2ME Application
  5. Jimmy’s Blog – Slide Number Puzzle Game with Echo2 Framework

:, , , , , , , , , , , , ,

76 Comments for this entry

  • Alphonse

    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

    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.

  • jimmy

    @pradnya:
    you can download JPOS at it website : http://www.jpos.org/

  • jimmy

    @Alphonse: just drop me some message at my pingbox or write you email address (I’ll remove it after I read it)

  • Aniket

    Thanks Jimmy ……….

  • Krishna

    Thanks.

    Did clear some of the doubts. is JPOS free even for commercial use?

  • Pritesh

    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.

    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

    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

    @@aniket.k.:

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

    Than ks
    Krishna

  • jimmy

    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

    @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

    @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

    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

    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

    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

    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

  • Edwin

    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

    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

    Hi!
    Another question JPOS can use BCD packet for send the message ?

    The message to my gateway is using BCD

  • Sanjay

    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

    @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

    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

    Jimmy, the problem is that the gateway that I use need BCD packets.

  • Sanjay

    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

    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

    @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

    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

    @sanjay:
    Looks good, all the mandatory fields are there. Just realized I forgot to mention #39 in my previous comment.

  • Cecil Millbern

    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

    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

    Hi Jimmy,

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

    Thanks for your time…

    Regards
    Jagan Reddy

  • Gaurav

    0067 ISO123456789 0800 82200000000000000400000000000000 0516124927 000001 301…
    Can anyone tell me what does 0067 specifies over here..

  • aji

    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

    @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

    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

    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

    @sirismail: I think you need to check the xml u used, is it the same with above example?

  • sandy

    thanks Jimmy.
    How much is the length of the bitmap in basic.xml?if i use 128 bitmap.

  • sirismail

    @jimmy yes its the same, i change it by a complete xml file but i have always the same error

  • sampath

    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

    Exactly where do one sign up for this blog? Cannot locate your blog feed icon in the footer.

  • Dino

    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

    Hello jimmy, do you know the source code to parse the data to BER-TLV format?

  • Venkat

    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

    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

    please tell me how to implement it on android.

Leave a Reply

Spam Protection by WP-SpamFree

Looking for something?

Use the form below to search the site:

Still not finding what you're looking for? Drop a comment on a post or contact us so we can take care of it!

Visit our friends!

A few highly recommended friends...