Andy Orrock | Payment Systems: Implementing the jPOS ISOPackager

In the jPOS mail forums (see jPOS Users and jPOS Developers), we see variations on a common question asked over and over again. It goes something along the lines of “hey, there’s a field that is supposed to contain seven bytes and I’m only getting four? Why?”

The vast majority of the time, the reason has to do with a mismatch between the ISO packager/depackager you’ve got deployed and the specific implementation of the ISO8583 interface that you’re trying to test and certify. Getting your packager in synch with the specific implementation decisions and nuances of a ‘real-life’ interface is the essential jPOS task. That’s why in the jPOS Programmers’ Guide, Alejandro mentions in a very clear manner that “It's very important to read your interchange specification(s) as soon as possible.” And, then later: “You can see it is very important to become familiar with your interchange specifications as soon as possible.”

Some people don’t grasp this crucial step of aligning the packager to a specification. The packager incorporates such ISO8583 implementation decisions as: the format of numerical values (display or BCD?); the character set used for alphanumerical values (ASCII or EBCDIC?); the length of each data field; whether the LLVAR or LLLVAR construct is in play for a particular field; whether numerical values should be padded to the full field length; and other important implementation policies that have been made by an organization (e.g., American Express, FDR, etc) and incorporated into their specifications.

We’ll go through the alignment steps here in this post. Many people search the web looking for ‘jPOS examples,’ so it seems appropriate to lay out a very clear and clean example here. I’ll use the American Express online interface here as our example. There are a number of reasons that make this interface the best example I can show you here:

AMEX’s interface specification (“Global Credit Authorization Guide”) is something AMEX makes freely available online.
AMEX’s Card Acceptance Processing Network (“CAPN”) initiative is resulting in a lot of re-certifications around the globe, so it’s an ideal time to consider making a commitment to jPOS.
As hinted at in the last point, AMEX’s interface is global in scope, meaning that this example is as apropos in Chile, India and Russia as it is in the US.
American Express’ interface is relatively simple and ‘thin’ – AMEX only makes use of 41 out of 128 possible ISO8583 data fields, meaning that I can comfortably walk through the entire ‘spec alignment’ exercise within the context of this single post.
AMEX’s spec is clear and well-written. The AMEX team provides top-notch technical support and structured walkthroughs (via teleconference). The supporting documentation (e.g., test scripts, telecom details) is also very helpful. All these factors improve your chances at success.

Now, we do the jPOS packager alignment with the spec. I mentioned above that AMEX only defines usage of 41 of the 128 ISO8583 fields. You can confirm for yourself in Section 3.3 of the Global Credit Authorization Guide that those ISO8583 fields are: 2; 3; 4; 7; 11; 12; 13; 14; 15; 19; 22; 24; 25; 26; 27; 30; 31; 32; 33; 35; 37; 38; 39; 41; 42; 43; 44; 45; 47; 48; 49; 52; 53; 54; 55; 56; 60; 61; 62; 63; and 64.

Reading the spec, you can also make the following observations:

All the numerical values are in ‘display’ form, not BCD. In other words, if there’s a 12-digit number, it’s expressed in 12 bytes, not crammed into 6 bytes (like a BCD representation would be).
All displayable characters are in EBCDIC, not ASCII.
All 41 ISO8583 fields in use are defined via the primary bit map; the secondary bit map is never in play (i.e., fields 65 – 128 are not used).
AMEX uses the ISO8583 1993 standard (not the 1987 standard that many others use as their framework).

Now, even though there are only 41 fields defined by the authorizing organization, it’s definitely a best practice to define all 128 fields in your isopackager (because you want your implementation to be as adaptable as possible). So, setting aside the bitmap field (which is ‘IFB_BITMAP’ class type – you should read the jPOS Programmers’ Guide for an explanation of the different class types that Alejandro and team have defined), you start with the default isopackager that comes with the jPOS download and make the following adjustments to the file to start to align with the AMEX spec:

Numeric fields become IFE_NUMERIC
Numeric fields with a variable length < 100 become IFE_LLNUM
Numeric fields with a variable length < 1000 become IFE_LLLNUM
Amount fields become IFE_AMOUNT
Alphanumeric fields become IFE_CHAR
Alphanumeric fields with a variable length < 100 become IFE_LLCHAR
Alphanumeric fields with a variable length < 1000 become IFE_LLLCHAR

[For a complete list of all ISOFieldPackager class types, refer to Appendix C of the jPOS Programmers' Guide.]

I tend to make those types of changes using global edits commands. The idea is to get the basic themes of a spec (here, display data in EBCDIC format) incorporated into the isopackager before focusing individually on each of the 41 fields.

Next, you put your focus on a close reading of each of fields in the spec and make sure that the isopackager matches them exactly. Many times, an organization – especially with some of the ‘PRIVATE USE’ fields like Field 62 and Field 63 – will define a field against your expectations; other times, they might re-use (or ‘steal’) a commonly used field for their own purpose. For each of the fields in play, it your responsibility to ensure that the length, class (and any special characteristics like padding) are in lockstep with the spec you’ve been handed.

Now, I’ve done that exercise for American Express CAPN, and the following XML file is the result of my efforts. I’ve highlighted in bold blue each of the 41 fields ‘in play’ by AMEX so that you can draw a straight line back to the specification.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE isopackager SYSTEM "genericpackager.dtd">

Hopefully, it goes without saying that you need to repeat this exercise for every interface you deploy. It should be obvious that you can’t take this file, rename it ‘fdr.xml’ and expect it to work straight away for a First Data interface. FDR North, for example, is BCD- and ASCII-based so it’s probably quicker and cleaner to start anew from Alejandro’s jPOS-bundled example instead of molding the FDR North isopackager from AMEX roots.

Comments

You can follow this conversation by subscribing to the comment feed for this post.

I am working on creating an interface to First Data North platform using the ISO 8593 Retail Standard. Can anyone suggest which one of the packagers in jPOS would be the best one to start with? Also does anyone know which Channel would work?

Thanks,

Jon

Posted by: Jon | Monday, August 06, 2007 at 16:34

Jon -

I'm sending you a copy of the fdr.xml packager via direct e-mail. That file implements the FDR North ISO8583 data structure.

Andy

Posted by: Andy | Tuesday, August 07, 2007 at 16:26

Hi,

I am working on ISO5883 message format, In particularly for Amex Authorization, I found this Message board is so informative along with the JPos Developers guide.

However there were still issues. I wondered about the following data field:
id="1"
length="16"
name="BIT MAP"
class="org.jpos.iso.IFB_BITMAP"/>

which version of American Global Authorization guide you used for this schema, As per the document I received the length for this field is 8 bytes.

If you can, Please forward me a copy of the above xml, alternative can I use your code with the copy right details with in the code.

Thanks,
Prasad

Posted by: prasad | Friday, September 14, 2007 at 05:22

Thanks for reading my blog.

The length parameter is immaterial for a field defined as a BITMAP. The fact that the AMEX bit map is defined as IFB_BITMAP means the packager knows the primary bit map is 8 bytes in length. I've got that field defined as 16 in all my implementations (some where the BITMAP is BCD, others where it's ASCII) without issue.

The AMEX packager presented in-line in this post is certified for usage in conjunction with AMEX's version 3.2 of their 'Global Credit Authorization Guide.'

Posted by: Andy Orrock | Friday, September 14, 2007 at 10:49

Andy,

Thanks for your time and support, I will go through your code.

Posted by: prasad | Friday, September 14, 2007 at 10:49

In further answer to Jon's post above, where he asks "Does anyone know which Channel would work (for FDR North)?"

Answer: None of the standard jPOS channel managers work. You need to write and implement a custom channel manager to manage the custom header - 'FD' - and custom trailer - 'FD' - with which FDR asks you to wrap messages.

Posted by: Andy Orrock | Friday, September 14, 2007 at 10:54

Hi you
I intend to use jPOS in my project but I have a thing to wonder: Is there some places in a ISO message in its standard format (described by ISO) for storing real length for each field? I ask you this silly question 'cause I think it's very difficult to parse an ISO message in string form who contains varied length fields, so we could not retrieve exactly value of a particular field by following its offset in the messsage.
Could you give me a guide, pls?
Thansk for your reply

Posted by: akinokehai | Sunday, October 14, 2007 at 23:50

Yes, well, that's the point entirely: it *is* difficult to parse an ISO8583 message via the eyeball method, which is why the jPOS packager is such a nice approach. You sound like you may be going about this via a reverse-engineering approach - trying to divine every from a trace. You need to get the spec, build a packager file from the spec, and iterate that until it parses correctly.

Posted by: Andy Orrock | Monday, October 15, 2007 at 09:39

Hi,
I have an another question to you. It's not an ISOPackager related question. It's about ISOMUX in jPOS: I'm using jPOS in my software which is deployed and runs in an application server (more precisely, IBM Websphere AS). ISOMUX uses Thread class to implement multithreading feature. I heard that an application server does not allow to launch a Thread manually. So my question is: Can jPOS run in a AS? If not, could you help me to resolve this problem, please?
Thank you so much.

Posted by: akinokehai | Tuesday, October 16, 2007 at 23:57

This is a question that needs to be posed on the jPOS Developers mailing list. See:

http://www.yahoogroups.com/group/jpos-dev/join

Posted by: Andy Orrock | Wednesday, October 17, 2007 at 09:48

Thank you for this nice blog post, when i review Global Credit Authorization Guide of AMERICAN EXPRESS , i found that the field type of field 11 "SYSTEMS TRACE AUDIT NUMBER" is : Alphanumeric &
special characters and i noticed that you made it numeric :
id="11"
length="6"
name="SYSTEM TRACE AUDIT NUMBER"
pad="true"
class="org.jpos.iso.IFE_NUMERIC"/>
are u mean that , or this is made by error ?

Posted by: Ahmed El-Malatawy | Thursday, April 24, 2008 at 07:14

Hi Ahmed -

Good observation. We're populating that value on our side in our acquirer implementation. We happen to use numeric values for our STAN, which AMEX is obligated to echo. So, the numeric definition causes no harm here.

Thanks for reading.

Andy Orrock

Posted by: Andy Orrock | Thursday, April 24, 2008 at 10:40

Hi! This website is very informative!
If any of you have to share the xml files for other card types such as visa, mastercard, etcs, that would help to everybody.
Thank you,

Pius

Posted by: Pius Yoon | Tuesday, May 06, 2008 at 16:00

Posted by: Pius Yoon | Tuesday, May 06, 2008 at 16:44

Thanks. Check out some of the Google Group conversations about packagers , like this one:

http://groups.google.com/group/jpos-users/browse_thread/thread/cabaaaebdf0a30c9

There's a couple of packagers referenced there that you can download as a resource.

Posted by: Andy Orrock | Tuesday, May 06, 2008 at 17:20

hi,
i want the information of bitmap conversion in ascii and other formats .can u provide with the examples please/

thanks inadvance
ensskumar.

Posted by: ensskumar | Monday, July 07, 2008 at 07:54