jPOS.org

jPOS Maven Archetype

apr — Sun, 10 Apr 2011 02:56:57 +0000

If you use Maven, there’s an extremely easy way to create a jPOS application now:

mvn archetype:generate \
  -DarchetypeGroupId=org.jpos \
  -DarchetypeArtifactId=jpos-archetype \
  -DarchetypeVersion=1.8.2 \
  -DarchetypeRepository=http://jpos.org/maven

If you don’t want to use the remote archetype, you can always ‘mvn install’ jPOS source code and then:

mvn archetype:generate -DarchetypeCatalog=local

UPDATED to use 1.8.2 instead of 1.8.1-SNAPSHOT
UPDATED to use ‘archetypeRepository’ instead of ‘DremoteRepositories’

jPOS Performance

apr — Mon, 13 Dec 2010 00:19:42 +0000

When companies — specially start-ups — ask us regarding jPOS performance, they usually tell us they need to support a massive load in the 1000+ TPS range. In order to give some perspective to these requirements, we always exchange some industry information with jPOS power developer Andy whose company manage some jPOS systems reaching 200M transactions per month, and today Andy sent me a very nice link (via OLS’ Ron Barker) about one of the largest acquirers in the world, during a really busy day, requiring 988 TPS, the important part:

“The record day on Nov. 26 translated to about 988 payment authorizations per second.”

So I thought it would be nice to start having some stable performance tests here and there in jPOS, so we can have something to measure where we are now, and even if it’s really fast for most applications, attempt to improve it.

Because many developers use jPOS just to pack and unpack ISO-8583 messages, I thought it would be nice to start by measuring where we are now in the pack/unpack department. I believe there’s plenty of room for optimization, but I hope you’ll agree that we are in pretty good shape.

I’ve just added a performance test to PackagerTestCase.java to try:

100000 pack operations
100000 unpack operations
100000 pack/unpack operations
100000 update, pack, and unpack operations

and here are the results:

>
  PACK tps=31531, peak=31531, avg=25156.00 [3779.2/3779.2]
  UNPACK tps=32371, peak=37026, avg=29081.00 [3047.9/6827.2]
  PACK/UNPACK tps=16605, peak=16634, avg=16144.25 [6254.2/13081.5]
  UPDATE/PACK/UNPACK tps=10862, peak=10862, avg=10815.16 [10430.9/23512.5]
  end [23512.6/23512.6]
>

We are operating with a pretty heavy message, way bigger than a real-life ISO-8583 message:

>
   id="0" value="0800"/>
   id="2" value="1234567890123456789"/>
   id="3" value="000000"/>
   id="4" value="000000000100"/>
   id="5" value="000000000200"/>
   id="6" value="000000000300"/>
   id="7" value="0611191024"/>
   id="8" value="12345678"/>
   id="9" value="12345678"/>
   id="10" value="12345678"/>
   id="11" value="000001"/>
   id="12" value="010203"/>
   id="13" value="0611"/>
   id="14" value="1001"/>
   id="15" value="0112"/>
   id="16" value="0112"/>
   id="17" value="0611"/>
   id="18" value="1234"/>
   id="19" value="858"/>
   id="20" value="032"/>
   id="21" value="400"/>
   id="22" value="000"/>
   id="23" value="001"/>
   id="24" value="003"/>
   id="25" value="00"/>
   id="26" value="01"/>
   id="27" value="1"/>
   id="28" value="000000100"/>
   id="29" value="000000200"/>
   id="30" value="000000300"/>
   id="31" value="000000400"/>
   id="32" value="123456"/>
   id="33" value="654321"/>
   id="34" value="ABCDEFGHIJKLMNOPQRSTUVWXYZ01"/>
   id="35" value="1234567890123456=12345678901234567890"/>
   id="36" value="THE QUICK BROWN FOX JUMPED OVER THE LAZY DOG"/>
   id="37" value="123456789ABC"/>
   id="38" value="123456"/>
   id="39" value="00"/>
   id="40" value="ABC"/>
   id="41" value="0001ABCD"/>
   id="42" value="123456789012345"/>
   id="43" value="JPOS CARD ACCEPTOR / WWW.JPOS.ORG       "/>
   id="44" value="jPOSjPOSjPOSjPOSjPOSjPOS"/>
   id="45" value="JPOSJPOSJPOSJPOSJPOSJPOS"/>
   id="46" value="ADDITIONAL DATA - ISO"/>
   id="47" value="ADDITIONAL DATA - NATIONAL"/>
   id="48" value="ADDITIONAL DATA - PRIVATE"/>
   id="49" value="032"/>
   id="50" value="032"/>
   id="51" value="032"/>
   id="52" value="0001020304050607" type="binary"/>
   id="53" value="1234567890123456"/>
   id="54" value="000000001000000000002000"/>
   id="55" value="ABCD"/>
   id="56" value="EFGH"/>
   id="57" value="IJKL"/>
   id="58" value="MNOP"/>
   id="59" value="QRST"/>
   id="60" value="UVWX"/>
   id="61" value="YZ01"/>
   id="62" value="A002"/>
   id="63" value="ABCDDCBA"/>
   id="64" value="CAFEBABECAFEBABE" type="binary"/>
   id="90" value="000000000000000000000000000000000000000000"/>
>

The last test is the more realistic one, because we tweak the message by changing some fields (i.e. 7,11,12,13), then pack and unpack.

In most jPOS applications, we receive a message, change a few fields, and send it back, for instance, a typical server will reply by just changing a few fields (i.e. 39, 38) and eventually resetting a few others. I think there’s tremendous room for optimization by caching the binary image of the packed message at the field level, avoiding a re-pack unless the field has changed.

Now that we know where we are, I hope to start testing some optimizations soon. You’re encourage to do so too.

BTW, these figures were taken on an MBP, it would be nice to have some feedback from runs on larger servers.

jPOS 1.8 series

apr — Sun, 28 Nov 2010 02:14:05 +0000

Starting in jPOS 1.8, we are going to manage jPOS builds using Maven.

There’s a mvn branch soon to be merged with master.

It seems 1.7.2 will be the last version of the old series managed by ‘ant’, will jump to 1.8.0 soon.

You can try 1.8.2 by adding to your pom.xml:

    >
      >jpos>
      >jPOS Central Repository>
      >http://jpos.org/maven>
      >default>
    >
 
    >
      >org.jpos>
      >jpos>
      >1.8.2>
    >

1.7.2 has already been committed to jPOS EE.

We’ll continue with the old module-based build system on jPOS-EE for a while.

UPDATE: changed 1.8-SNAPSHOT to 1.8.0
UPDATE: changed 1.8-SNAPSHOT to 1.8.2

jPOS in Github

apr — Sat, 06 Nov 2010 20:42:10 +0000

Quick note to let you know that as of subversion r3019, new jPOS development will take place in github.com/jpos.

The jPOS Project Guide has been updated.

JRuby support

apr — Sun, 31 Oct 2010 14:42:36 +0000

/by apr/

I’ve spent a great time listening to great talks at RubyConf Uruguay organized by Cubox. Now I totally understand when they say “Old School Teamwork Fun People, Serious pros: The mix you’re looking for” in their website. It is exactly that.

I was delighted to listen to Charles Nutter (JRuby’s author) talk but was sad with this tweet from him a few hours ago:

So I tried latest JRuby on latest jPOS, it took just a few minutes. I’ve added an optional ‘jruby’ module to jPOS-EE (just depends on the ‘commons’ module) and you can now deploy a QBean that looks like this:

 class='org.jpos.jruby.Ruby'>
  puts "Hello jRuby!"
>

And that’s all there is to it

If you want to try this in a new small project, you can follow the HOWTO in jPOS Project Guide around page 35, just add the ‘commons’ and ‘jruby’ module as svn:externals, and you’d be ready to go.

And the output, you guess it:

Hello jRuby!

Mr. Nutter, Welcome to this southern Montevideo and beware with the dogs here

jPOS-EE Things

apr — Wed, 28 Jul 2010 17:23:03 +0000

Inspired by this talk, I got reminded to play with EAVs in jPOS-EE.

I’ve created a jPOS-EE modules called “things” that I believe it’s a good thing to have in most applications.

I don’t think this is a one-size-fits-all solution, you probably don’t want to store your core tables (such as the transaction log, miniGL stuff, whatever) using this open schema approach, but for everything else, having this open schema can save your day (in the same way a ‘flags’ field in most tables can help at some point).

Using it is very simple, you create a “thing” using the ThingsManager:

   DB db = new DB();   
   ThingsManager mgr = new ThingsManager(db);
   Thing t = mgr.create("MyThing");

Then you can put Strings, Longs, Dates, Timestamps, long Strings and BigDecimals to your thing, i.e:

   t.put ("AString",  "This is a string");
   t.put ("ALong", Long.MAX_VALUE);
   t.put ("MyInteger", i);
   t.put ("Date", d);
   t.put ("Timestamp", new Timestamp(now));
   t.put ("BigDecimal", ONE_THOUSAND);
   t.putText("Text", "The quick brown fox is brown and the dog is lazy, and jumps.");

The ThingsManager has some handy methods already, and we’ll add more as the need arise.

public List getAll (String type) ;
public Thing getLast (String type);
public List listByStringName (String type, String name);
public List listByStringValue (String type, String value);
public List listByStringNameValue (String type, String name,String value);
public List listByTextName (String type, String name);
public List listByTextValue (String type, String value);
...
...

Some immediate use comes to mind, we could use this to provide a more type-safe, versionable version of our existing SysConfig table (i.e. we could have a thing called ‘SysConfig’ and keep previous versions as ‘SysConfig;1′, ‘SysConfig;2′, etc. (or another numbering scheme if you find this one too VMS-eske). It’s also good to handle extremely proprietary stuff such as fee configuration, currency exchange, etc. found in many jPOS applications.

The things module is available in jPOS-EE as of r307

Q2 transient services

apr — Sat, 24 Jul 2010 23:35:05 +0000

In jCard and jPTS we use the concept of Stations, we have Source Stations (SS), Destination Stations (DS), Monitoring Stations (MS), Control Stations (CS) and Cryptographic Stations (HSMS), etc.

Every station usually requires a handful Q2 services (QBeans), such as a MUX or MUXPool, one or more ChannelAdaptors with their filters, LogonManager, KeyExchangeManagers, eventually an independent logger, etc.

You can configure those manually for a small set of stations, you can also use some scripts, but in order to support a large number of stations, and to easily manage them from the UI, we use a database to keep their basic configuration (station type, host, port, timeouts, etc.) and then use these new transient services provided by Q2.

When Q2 starts, it’s create an unique transient UUID, that FYI is displayed by the SystemMonitor task:

 realm="org.jpos.q2.qbean.SystemMonitor" at="Sat Jul 24 20:14:14 UYT 2010.495">
  >
    >jPOS 1.6.9 r2950>
    >e424833b-c2c1-4f8b-b743-8a69271912a2>
    >00:00:00.170>
  >
   ...
   ...
>

When you deploy a QBean using Q2′s deployElement method (which is now public), you can flag that qbean as ‘transient’ (there’s a boolean parameter). In that case, Q2 will remove the file on exit, but just in case the system crashes, it also adds a ‘transient’ attribute to the QBean, i.e:

 class="org.jpos.q2.iso.QServer" logger="Q2"  instance="e424833b-c2c1-4f8b-b743-8a69271912a2">
  ...
  ...
>

The next time it runs, Q2 will generate a new instance ID, so in the rare situation where an old deployment descriptor is present in the deploy directory, it will be ignored and deleted (as it should have been removed at the previous exit).

Q2.deployElement is a handy method that requires a JDom Element. If you are not a member of the JDom church, you can always create your QBean manually, you can get to know Q2′s instance ID by calling its getInstanceId() method that gives you an UUID,.

Note: when you deploy a bundle using Q2 –config=/path/to/your/bundle, Q2 now flags the exploded descriptors as transient.

This is available as of jPOS 1.6.9 r2950

jPOS 1.6.8 has been released

apr — Fri, 02 Jul 2010 11:57:53 +0000

Just a quick note to let you know that jPOS 1.6.8 has been released (ChangeLog).

This is a maintenance release that fixes several bugs and adds some reasonable defaults that can avoid some problems (i.e.TransactionManager’s paused-timeout default issue).

jPOS-EE users just ‘svn update’ and you’ll get it from modules/jpos/lib/jpos.jar (r290).

Technology XYZ

apr — Fri, 18 Jun 2010 16:35:31 +0000

/by apr/

There are several recurring questions that jPOS new users keep asking:

I want to build jPOS in Netbeans/Eclipse/IDEA
I want to log to log4j
I want to run it in Tomcat/Spring/Websphere/Weblogic/JBoss (note the mix of technologies here)

Here is how I read them:

I want to build jPOS in my IDE because I don’t have a clue about compiling a java program using ant and I’m lazy to learn something new. I don’t even know how to ‘cd’ to the jPOS directory.
I know how to configure log4j and don’t want to learn how to configure other stuff. jPOS comes pre-configured to use a very nice PCI-compliant log, but I’m so lazy that I don’t know that, so I ask how to use it with log4j.
I don’t know how to start a Java application as a daemon/service, but my Tomcat/Spring/Websphere somehow is already running in my server (the previous admin left it running before quitting), so I want to run jPOS inside one of those.

So people don’t care about the business logic, about why they need jPOS, they just want to have something running in their environment, even if the environment is not the best choice to run their jPOS applications.

jPOS is a first class application that will process transactions worth millions of dollars for you. You should consider asking us what’s the best environment, the best DB, the OS to run jPOS instead of forcing it to run in weird ways.

Amen.

What is jCard?

apr — Mon, 01 Mar 2010 21:55:03 +0000

/by apr/

As a follow-up to the initial post about jCard and jPTS, I’d like to explain what is jCard after all.

jCard is an interface between the ISO-8583 world and a double-entry accounting system.

– or better yet –

jCard is an interface between the ISO-8583 v2003 based jPOS-CMF world and a
multi-layer, multi-currency general purpose double-entry accounting system (miniGL).

Here is an the initial ER diagram of the core components that we used at design time, although somehow changed to support customer’s requirements, it still gives you the idea of how the pieces fit together:

You can see here that an Issuer has CardProducts which in turn has Cards. A Card is our handle to the CardHolder which in turn can have multiple GL Accounts (think Checking, Savings, Stored Value accounts).

Imagine this little chart of accounts for a pre-paid card:

As seen from jCard’s perspective, a deposit transaction will debit our ‘Received money’ account (an asset) and credit the Cardholder’s SV account (it’s a liability now for us).

So a deposit transaction will look like this:

USD 100 goes to the ‘Received Money’ account and 100 to the Cardholder’s account.

If you enlarge the picture, you’ll see a little ’840′ number to the right of the account code, i.e. 11.001.00₈₄₀, that’s our layer (in this case the accounting USD layer, 840 is the ISO-4217 currency number).

Here is a purchase transaction that involve some fees, followed by a reversal:

You can see we just change who we owe to, instead of owing this money to the cardholder, we owe it now to the acquirer (or merchant/branch, depending on the situation).

The ISO-8583 side honors the jPOS CMF, so this purchase transaction looks like this:

        direction="incoming">
          id="0" value="2200"/>
          id="2" value="604955_________0001"/>
          id="3" value="013000"/>
          id="4" currency="840" type="amount" value="20.00"/>
          id="7" value="0301173541"/>
          id="11" value="000000000083"/>
          id="12" value="20100301173541"/>
          id="13" value="000301"/>
          id="14" value="1012"/>
          id="17" value="0301"/>
          id="32" value="000001"/>
          id="37" value="010535141630"/>
          id="41" value="29110001        "/>
          id="42" value="001001"/>
         > id="43">
            id="2" value="jCard Selftest system"/>
            id="4" value="Montevideo"/>
            id="5" value="MV "/>
            id="7" value="UY "/>
         >
          id="46" value="07D84020000005000000001D840200000050"/>

This particular CardProduct has a flat fee of USD 3.50 plus a 3.25% for CashAdvance transactions, this is configured like this:

mysql> select * from cardproduct_fees where id = 1;
+----+--------+----------------------+
| id | fee    | type                 |
+----+--------+----------------------+
|  1 | 3.2500 | CashAdvance.%.840    |
|  1 | 3.5000 | CashAdvance.flat.840 |
+----+--------+----------------------+

that’s why we ended-up charging USD 24.65.

For those of you familiar with jPOS, looking at its TransactionManager main configuration may give you an idea of what we are talking about here:

 class="org.jpos.transaction.TransactionManager" logger="Q2">
  name="queue" value="JCARD.TXN" />
  name="sessions" value="2" />
  name="debug" value="true" />
 
  class="org.jpos.jcard.PrepareContext" logger="Q2" realm="PrepareContext" />
  class="org.jpos.transaction.Open" logger="Q2" realm="open">
   name="checkpoint" value="open" />
   name="timeout" value="300" />
 >
 
  class="org.jpos.jcard.Switch" logger="Q2" realm="Switch">
   name="100.30" 
           value="balanceinquiry prepareresponse logit close sendresponse" />
   name="100.00" 
           value="authorization prepareresponse logit close sendresponse" />
   name="100.02" 
           value="auth-void prepareresponse logit close sendresponse" />
   name="100.20" 
           value="refund prepareresponse logit close sendresponse" />
   name="100.22" 
           value="refund-void prepareresponse logit close sendresponse" />
 
   name="200.00" 
           value="financial prepareresponse logit close sendresponse" />
   name="200.01" 
           value="financial prepareresponse logit close sendresponse" />
   name="200.02" 
           value="purchase-void prepareresponse logit close sendresponse" />
   name="200.20" 
           value="financial-refund prepareresponse logit close sendresponse" />
   name="200.21" 
           value="financial-deposit prepareresponse logit close sendresponse" />
   name="200.22" 
           value="financial-refund-void prepareresponse logit close sendresponse" />
   name="200.40" 
           value="transfer prepareresponse logit close sendresponse" />
 
   name="220.00.0000" 
           value="completion prepareresponse logit close sendresponse" />
   name="220.20.0000" 
           value="refund-completion prepareresponse logit close sendresponse" />
   name="220.00.1000" 
           value="force-post prepareresponse logit close sendresponse" />
   name="220.00.2000" 
           value="force-post prepareresponse logit close sendresponse" />
   name="220.20.1000"
           value="refund-force-post prepareresponse logit close sendresponse" />
   name="220.20.4500"
           value="refund-force-post prepareresponse logit close sendresponse" />
 
   name="420.00.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="420.01.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="420.02.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="420.20.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="420.21.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="420.40.0000" 
           value="reversal prepareresponse logit close sendresponse" />
   name="304.301.CUSTOMER"  
           value="add_customer_record prepareresponse logit close sendresponse" />
   name="304.301.MERCHANT"  
           value="add_merchant_record prepareresponse logit close sendresponse" />
   name="unknown"  
           value="notsupported prepareresponse close sendresponse" />
 >
 
  class="org.jpos.jcard.ProtectDebugInfo" logger="Q2" realm="ProtectDebug" />
  class="org.jpos.transaction.Debug" logger="Q2" realm="debug" />
 
  name="notsupported">
   class="org.jpos.jcard.NotSupported" logger="Q2" 
    realm="not-supported" />
 >
 
  name="balanceinquiry">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13,AMOUNT,PAN,41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
   class="org.jpos.jcard.BalanceInquiry" 
    logger="Q2" realm="balance-inquiry" />
 >
 
  name="authorization">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
    name="checkpoint"   value="check-card" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal">
    name="checkpoint"   value="check-terminal" />
  >
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer">
    name="checkpoint"   value="check-acquirer" />
  >
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account">
    name="checkpoint"   value="select-account" />
  >
   class="org.jpos.jcard.CheckPreviousReverse" 
    logger="Q2" realm="check-previous-reverse">
    name="checkpoint"   value="check-previous-reverse" />
  >
   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity">
    name="checkpoint"  value="check-velocity" />
  >
   class="org.jpos.jcard.Authorization" 
    logger="Q2" realm="authorization">
    name="checkpoint"   value="authorization" />
  >
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
  name="financial">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.CheckPreviousReverse" 
    logger="Q2" realm="check-previous-reverse" />
   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity" />
   class="org.jpos.jcard.Financial" 
    logger="Q2" realm="financial" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
 
  name="refund">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity" />
   class="org.jpos.jcard.Refund" logger="Q2" realm="refund" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
  name="financial-refund">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity" />
   class="org.jpos.jcard.FinancialRefund" 
   logger="Q2" realm="financial-refund" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
 
  name="financial-deposit">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.FinancialDeposit" 
   logger="Q2" realm="financial-deposit" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
 
  name="reversal">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 25,41, ORIGINAL_DATA_ELEMENTS" />
    name="optional"  value="17,24,25,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="window" value="259200" />
    name="fields" value="stan, amount, currency, card, original-tx-timestamp" />
  >
   class="org.jpos.jcard.Reverse" logger="Q2" realm="reverse" />
 >
 
  name="completion">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN,25,38,41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="original-itc" value="100.00" />
    name="window" value="2592000" />
    name="fields" value="card, approvalNumber, currency" />
  >
   class="org.jpos.jcard.Completion" logger="Q2" realm="reverse" />
 >
 
  name="refund-completion">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13,AMOUNT,PAN,25,38,41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="original-itc" value="100.20" />
    name="window" value="2592000" />
    name="fields" value="card, approvalNumber, currency" />
  >
   class="org.jpos.jcard.Completion" logger="Q2" realm="completion" />
 >
 
  name="force-post">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN,25,41" />
    name="optional"  value="17,24,32,37,38,39,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.ForcePost" 
      logger="Q2" realm="force-post" />
 >
  name="refund-force-post">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN,25,41" />
    name="optional"  value="17,24,32,37,38,39,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.RefundForcePost" 
      logger="Q2" realm="refund-force-post" />
 >
 
  name="transfer">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />
   class="org.jpos.jcard.CheckPreviousReverse" 
    logger="Q2" realm="check-previous-reverse" />
   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity" />
   class="org.jpos.jcard.Transfer" 
    logger="Q2" realm="transfer" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >
 >
 
  name="purchase-void">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41, ORIGINAL_DATA_ELEMENTS" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="window" value="259200" />
    name="fields" value="stan, amount, currency, card, original-tx-timestamp" />
    name="original-itc" value="200.00" />
  >
   class="org.jpos.jcard.Void" logger="Q2" realm="void" />
 >
  name="auth-void">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41, ORIGINAL_DATA_ELEMENTS" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="window" value="259200" />
    name="fields" value="stan, amount, currency, card, original-tx-timestamp" />
    name="original-itc" value="100.00" />
  >
   class="org.jpos.jcard.Void" logger="Q2" realm="void" />
 >
 
  name="close">
   class="org.jpos.transaction.Close" logger="Q2" realm="open">
    name="checkpoint" value="close" />
  >
 >
  name="refund-void">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41, ORIGINAL_DATA_ELEMENTS" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="window" value="259200" />
    name="fields" value="stan, amount, currency, card, original-tx-timestamp" />
    name="original-itc" value="100.20" />
  >
   class="org.jpos.jcard.Void" logger="Q2" realm="void" />
 >
  name="financial-refund-void">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41, ORIGINAL_DATA_ELEMENTS" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.CheckCard" 
      logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >
   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />
   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />
   class="org.jpos.jcard.FindOriginal" logger="Q2" realm="findoriginal">
    name="window" value="259200" />
    name="fields" value="stan, amount, currency, card, original-tx-timestamp" />
    name="original-itc" value="200.20" />
  >
   class="org.jpos.jcard.Void" logger="Q2" realm="void" />
 >
 
  name="prepareresponse">
   class="org.jpos.jcard.PrepareResponse" logger="Q2" realm="prepareresponse">
    name="locale" value="JCARD" />
    name="checkpoint"   value="prepare-response" />
  >
 >
  name="logit">
   class="org.jpos.jcard.LogIt" logger="Q2"
    realm="log-it">
    name="checkpoint"   value="log-response" />
  >
 >
 
  name="sendresponse">
   class="org.jpos.jcard.SendResponse" logger="Q2" realm="sendresponse" />
 >
 
  name="add_customer_record">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="7,11,12,24,101" />
    name="optional"  value="2,72,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.AddCustomer" 
      logger="Q2" realm="add-customer">
    name="chart"        value="jcard" />
    name="customers-account" value="21" />
    name="issuer" value="1" />
    name="card-product" value="1" />
    name="final-account" value="00" />
    name="account-description-00" value="Stored Value" />
    name="account-currency-00" value="840" />
    name="account-additional-mapping-00" value="31, 32, 33, 34, 35, 36" />
 
    name="final-account" value="40" />
    name="account-description-40" value="Stored Points" />
    name="account-currency-40" value="840" />
    name="account-additional-mapping-40" value="" />
    name="kid" value="&KID;" />
  >
 >
 
  name="add_merchant_record">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="7,11,12,24,101" />
    name="optional"  value="2,32,42,72,111" />
  >
   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >
   class="org.jpos.jcard.AddMerchant" 
      logger="Q2" realm="add-merchant">
  >
 >
>

So the previous transaction was a 200.01 (MTI=200, Processing code 013000), so we processed the following groups:

financial
prepareresponse
logit
sendresponse

The financial group looks like this:

First, we perform some sanity checks, we verify that the mandatory fields are present, we allow some optional fields too.

 name="financial">
   class="org.jpos.jcard.CheckFields" logger="Q2" realm="CheckRequiredFields">
    name="mandatory" value="PCODE,7,11,12,13, AMOUNT, PAN, 41" />
    name="optional"  value="17,24,32,37,42,43,46,60,63,111" />
  >
>

Then we create a TranLog record (that’s our master transaction log file)

   class="org.jpos.jcard.CreateTranLog" logger="Q2" 
      realm="create-tranlog">
    name="queue"        value="JCARD.TXN" />
    name="space"        value="tspace:default" />
    name="capture-date" value="capture-date" />
    name="checkpoint"   value="create-tranlog" />
    name="node"         value="01" />
  >

We check that the card exists, it’s valid, belongs to a CardHolder, etc. We do this in a PCI compliant way, that ‘KID’ configuration there is the DUKPT BDK Key ID.

   class="org.jpos.jcard.CheckCard"    
   logger="Q2" realm="checkcard">
    name="kid" value="&KID;" />
  >

The terminal has to be valid too:

   class="org.jpos.jcard.CheckTerminal"    
   logger="Q2" realm="checkterminal" />

And so is the acquirer (we’ll have to pay them at some point)

   class="org.jpos.jcard.CheckAcquirer"    
   logger="Q2" realm="checkacquirer" />

We know the Card, so we know the CardHolder. We know the CardHolder has accounts, and based on the processing code (data element 3), we choose which account to use (checking, saving, credit, stored value, loyalty, whatever)

   class="org.jpos.jcard.SelectAccount" 
    logger="Q2" realm="select-account" />

It can happen under certain scenarios (mostly due to small network outages) that we could receive a reversal for a given transaction before or almost at the same time as the transaction itself, so we check if this transaction was previously reversed:

   class="org.jpos.jcard.CheckPreviousReverse" 
    logger="Q2" realm="check-previous-reverse" />

Then, based on the CardProduct, we can perform multiple velocity checks:

   class="org.jpos.jcard.CheckVelocity"    
   logger="Q2" realm="checkvelocity" />

And now we are ready to generate the GL transaction and compute the balances after that.

   class="org.jpos.jcard.Financial" 
    logger="Q2" realm="financial" />
   class="org.jpos.jcard.ComputeBalances" 
      logger="Q2" realm="compute-balances">
     name="checkpoint" value="compute-balances" />
  >

Here is the source code for org.jpos.jcard.Financial

public class Financial extends Authorization {
    public int prepare (long id, Serializable context) {
        return super.prepare (id, context);
    }
    protected short getLayerOffset() {
        // financial transactions goes to the main layer for the
        // given currency
        return 0;  
    }
    protected String getTransactionName() {
        return "Financial";
    }
}

Pretty simple, huh? Please pay attention to that ‘getLayerOffset()’ method that returns 0.

The Authorization participant is slightly more complex:

public class Authorization extends JCardTxnSupport {
    public static final String FEE_PREFIX = "CashAdvance";
 
    public Authorization() {
        super();
    }
    public int prepare (long id, Serializable context) {
        Context ctx = (Context) context;
        try {
            ctx.checkPoint ("authorization-start");
            TranLog tl  = (TranLog) ctx.get (TRANLOG);
            GLSession gls = getGLSession(ctx);
            ISOMsg m = (ISOMsg) ctx.get (REQUEST);
            Card card = (Card) ctx.get (CARD);
            CardHolder cardHolder = (CardHolder) ctx.get (CARDHOLDER);
            Issuer issuer = (Issuer) ctx.get (ISSUER);
 
            String accountType = ctx.getString (PCODE_ACCOUNT_TYPE);
            BigDecimal amount = (BigDecimal) ctx.get (AMOUNT);
            BigDecimal acquirerFee = getAcquirerFee (m);
            BigDecimal issuerFee = ZERO;
 
            assertNotNull (issuer, INVALID_REQUEST, "Invalid Issuer");
            assertNotNull (card, INVALID_REQUEST, "Invalid Card");
            assertNotNull (card.getCardProduct(), INVALID_REQUEST, "Invalid CardProduct");
            assertNotNull (
                 card.getCardProduct().getIssuedAccount(), INVALID_REQUEST, 
                "Invalid CardProduct Issued Account"
            ); 
            assertNotNull (cardHolder, INVALID_REQUEST, "Invalid CardHolder");
            assertNotNull (amount, INVALID_AMOUNT);
            assertFalse (ZERO.equals (amount), INVALID_AMOUNT, "Zero amount not valid");
            assertNotNull (accountType,
                INVALID_REQUEST, "Invalid processing code"
            );
            assertFalse(REFUND_ACCOUNT_TYPE.equals (accountType),
                INVALID_REQUEST, "Refund account not allowed"
            );
            String acctid = accountType+"."+ctx.getString(CURRENCY);
            FinalAccount acct = (FinalAccount) 
                cardHolder.getAccounts().get (acctid);
 
            assertNotNull (acct, 
                ACCOUNT_NOT_FOUND, 
                "Account type '"+acctid+"' is not defined");
 
            Journal journal = issuer.getJournal();
            assertNotNull (
                journal, SYSERR_DB, 
                "Journal not found for issuer " + issuer.getId() + " ("
                + issuer.getName() + ")"
            );
 
            ctx.checkPoint ("authorization-pre-lock-journal");
            gls.lock (journal, acct);
            ctx.checkPoint ("authorization-post-lock-journal");
 
            short currency = getCurrency (ctx.getString(CURRENCY));
            short[] realAndPending = new short[] {
                currency, (short) (currency + PENDING_OFFSET)
            };
            BigDecimal balance = gls.getBalance (journal, acct, realAndPending);
            ctx.checkPoint ("authorization-compute-balance");
            BigDecimal amountPlusFees = amount.add(acquirerFee);
 
            ctx.put (ACCOUNT, acct);
            String surchargeDescription = null;
            if (amountPlusFees.compareTo (balance) > 0) {
                BigDecimal creditLine = gls.getBalance (
                    journal, acct, 
                    new short[] { (short)(currency+CREDIT_OFFSET) }
                );
                ctx.checkPoint ("authorization-get-credit-line");
                if (acct.isDebit())
                    creditLine = creditLine.negate();
 
                StringBuilder sb = new StringBuilder();
                issuerFee = issuerFee.add(calcSurcharge (ctx, card, amount, FEE_PREFIX, sb));
                if (sb.length() > 0)
                    surchargeDescription = sb.toString();
                amountPlusFees = amountPlusFees.add (issuerFee);
                if (!isForcePost() && amountPlusFees.compareTo
                    (balance.add(creditLine)) >= 0) 
                {
                    throw new BLException (NOT_SUFFICIENT_FUNDS, 
                        "Credit line is " + creditLine 
                       +", issuer fee=" + issuerFee); 
                }
            }
            Acquirer acquirer = (Acquirer) ctx.get (ACQUIRER);
 
            GLTransaction txn = new GLTransaction (
                getTransactionName() + " " + Long.toString(id)
            );
            txn.setPostDate ((Date) ctx.get (CAPTURE_DATE));
            txn.createDebit (
                acct, amountPlusFees, null, 
                    (short) (currency + getLayerOffset())
            );
            txn.createCredit (
                acquirer.getTransactionAccount(), amount, 
                null, (short) (currency + getLayerOffset())
            );
            if (!ZERO.equals(issuerFee)) {
                txn.createCredit (
                    card.getCardProduct().getFeeAccount(), issuerFee, 
                    surchargeDescription, (short) (currency + getLayerOffset())
                );
                ctx.put (ISSUER_FEE, issuerFee);
            }
            if (!ZERO.equals(acquirerFee)) {
                txn.createCredit (
                    acquirer.getFeeAccount(), acquirerFee, 
                    null, (short) (currency + getLayerOffset())
                );
                ctx.put (ACQUIRER_FEE, acquirerFee);
            }
            gls.post (journal, txn);
            ctx.checkPoint ("authorization-post-transaction");
            tl.setGlTransaction (txn);
            ctx.put (RC, TRAN_APPROVED);
            ctx.put (APPROVAL_NUMBER, getRandomAuthNumber());
            return PREPARED | NO_JOIN;
        } catch (ObjectNotFoundException e) {
            ctx.put (RC, CARD_NOT_FOUND);
        } catch (GLException e) {
            ctx.put (RC, NOT_SUFFICIENT_FUNDS);
            ctx.put (EXTRC, e.getMessage());
        } catch (BLException e) {
            ctx.put (RC, e.getMessage ());
            if (e.getDetail() != null)
                ctx.put (EXTRC, e.getDetail());
        } catch (Throwable t) {
            ctx.log (t);
        } finally {
            checkPoint (ctx);
        }
        return ABORTED;
    }
    public void commit (long id, Serializable context) { }
    public void abort  (long id, Serializable context) { }
 
    protected short getLayerOffset() {
        return PENDING_OFFSET;
    }
    protected String getTransactionName() {
        return "Authorization";
    }
    protected BigDecimal calcSurcharge 
        (Context ctx, Card card, BigDecimal amount, StringBuilder detail) 
    {
        BigDecimal issuerFee = ZERO;
        Map<string ,BigDecimal> fees = card.getCardProduct().getFees();
        BigDecimal flatFee = fees.get(
            FEE_PREFIX + FEE_FLAT + ctx.getString(CURRENCY)
        );
        BigDecimal percentageFee = fees.get(
            FEE_PREFIX + FEE_PERCENTAGE + ctx.getString(CURRENCY)
        );
        if (flatFee != null) {
            issuerFee = issuerFee.add (
                flatFee.setScale(2, ROUNDING_MODE)
            );
            detail.append ("Surcharge: $");
            detail.append (flatFee);
        }
        if (percentageFee != null) {
            issuerFee = issuerFee.add (
                amount.multiply(
                    percentageFee.movePointLeft(2)
                ).setScale(2, ROUNDING_MODE)
            );
            if (flatFee != null)
                detail.append ('+');
            else
                detail.append ("Surcharge: ");
            detail.append (percentageFee);
            detail.append ('%');
        }
        return issuerFee;
    }
    protected boolean isForcePost () {
        return false;
    }
}
string>

In this case getLayerOffset() returns PENDING_LAYER (a constant set to 1000).

So what happens here is that when we perform an authorization, we impact the PENDING layer (i.e. 1840 if the transaction was in USD) instead of the ACCOUNTING layer (840).

When we compute the USD ACCOUNTING BALANCE, we check for transactions on the 840 layer, but when we check for the available balance, we take into account layer 840 merged with layer 1840 (this is why miniGL has layers).

So to recap, this is a financial transaction (MTI 200):

And here is an interesting sequence:

Pre-Auth USD 100
Void of the preauth
Reversal of the previous void (authorization becomes active again, if available funds permit)
Partial completion for USD 90

If you pay attention to the layers involved, you can see that the pre-auth works on layer 1840 while the completion works on 840, the accounting layer (offset=0).

We use that layers scheme to handle overdrafts and credit account (offset is 2000), so for a credit account, we pick the balances from 840,1840,2840 (provided the transaction is performed in USD).

jCard was developed in paralell with the jPOS CMF and the jCard selftest facility, based on jPOS-EE’s clientsimulator.

Whenever we touch a single line of it, we automatically run an extensive set of transactions that gives us some confidence that we are not introducing any major issue, i.e:

...
...
    77: Card 6009330000000020 - savings balance is 102     [OK] 50ms.
    78: Card 6009330000000020 - $1 from checking to savings with $0.50 fee [OK] 126ms.
    79: Card 6009330000000020 - savings balance is 104     [OK] 48ms.
    80: $95.51 from checking to savings with no fee (NSF)  [OK] 78ms.
    81: $95.01 from checking to savings with $0.50 fee (NSF) [OK] 75ms.
    82: $95.00 from checking to savings with $0.50 fee - GOOD [OK] 70ms.
    83: Card 6009330000000020 - savings balance is now 199 [OK] 111ms.
    84: Reverse previous transfer                          [OK] 57ms.
    85: Reverse previous transfer (repeat)                 [OK] 70ms.
    86: savings balance after reverse is 104               [OK] 58ms.
    87: Withdrawal $20 from credit account with 0.50 fee   [OK] 85ms.
    88: credit balance check                               [OK] 59ms.
    89: Reverse withdrawal                                 [OK] 57ms.
    90: credit balance check - should be back to 1000      [OK] 50ms.
    91: $100.00 from credit to checking with $0.75 fee - GOOD [OK] 138ms.
    92: Reverse transfer                                   [OK] 52ms.
    93: credit balance check - should be back to 1000      [OK] 57ms.
    94: POS Purchase $20 from credit account with 0.50 fee to be voided [OK] 107ms.
    95: Void previous transaction                          [OK] 51ms.
    96: Void repeat                                        [OK] 24ms.
    97: Auth for $100 from savings account, no fees        [OK] 82ms.
    98: Void completed auth                                [OK] 51ms.
    99: Void repeat                                        [OK] 29ms.
    100: Invalid completion for USD 90.00 (previously voided) [OK] 34ms.
    101: Reverse void                                       [OK] 56ms.
    102: Reverse void retransmission                        [OK] 32ms.
    103: completion for USD 90.00 (void has been reversed)  [OK] 48ms.
    104: completion for USD 90.00 retransmission            [OK] 38ms.
    105: check savings balance - should be $14.00           [OK] 110ms.
    106: Refund for $16                                     [OK] 70ms.
    107: Reverse previous refund                            [OK] 47ms.
    108: refund reversed, balance back to 0.00              [OK] 67ms.
...
...

I hope that this post can give you an idea of what jCard is and why we are sometimes quiet on the blog, we are having fun developing all this.