'On-boarding' a new Authorization Interface in jPOS

People often ask about jPOS:  How quickly can I get an authorization interface up and running?  [NOTE:  I'm answering this one from an Acquirer's perspective and I'm not taking into account any PIN translation issues within the context of this answer.]  Before answering, there's two factors to get on the table:

1. The length of time needed to establish TCP/IP-level connectivity.  This is always the 'opening' critical path.  Get you telecom team involved from Day 1 and get working on these details.
2. How the authorization partner works with you in terms of allotting test time.  If they've got an unmanned, 24x7 test system up and running where you can iterate your way through continuous improvement, well - good for you.  You'll make rapid headway.  If, however, the remote endpoint partner is the type that has you book 60-minute slots a week in advance and provides 'supervision' for the test, well - bad for you: welcome to gating factor #2.

With those caveats out of the way, hey, there's very good news to report on the jPOS front.  The auth endpoint 'onboarding' is at the very heart of the business problems that jPOS seeks to solve for its community of users.  There's a good repeatable process in place for you to follow.  The jPOS architecture makes heavy use of XML-based configuration files to facilitate the on-boarding of new features and new authorizer endpoints.

The repeatable process for adding a new endpoint goes as follows (covering it here at a high level):

MOST IMPORTANT:  Read your authorizer’s specification and arrange a spec walkthrough with them.  It's hard to overemphasize the importance of this step.  It's the key event.

1.  Incorporate the spec + info gleaned in the walkthrough info into a jPOS XML ‘packager’ file, in which (in an ISO8583-based interface, as an example) all 128 ISO fields are defined. The resulting packager would contain 128 field definitions appearing as follows (field 2 shown here as example):
   
   <isofield
        id="2"
        length="19"
        name="PAN - PRIMARY ACCOUNT NUMBER"
        pad="false"
   class="org.jpos.iso.IFB_LLNUM"/>
   
   For a discussion of the repeatable process that can be used to implement a packager, refer to this recent in-depth look at it. 
   
   [Refer to Chapter 7 of the jPOS Programmer’s Guide for further discussion on Implementing Custom (ISO) Packagers - refer to the bottom of this post for more info on the Programmer's Guide.]
   
2. Determine the ‘channel model’ used by endpoint. [If standard (e.g., NACChannel, VAPChannel, ASCIIChannel, etc.), choose model from jPOS repository; else, write and incorporate your own model.]
   
   
3. Configure your channel XML file(s).  Here's an example:   
   
   <channel-adaptor name='fdr'
       class="org.jpos.q2.iso.ChannelAdaptor" logger="Q2">
   <channel class="org.jpos.fdr.FDRChannel" logger="Q2" realm="fdr-channel"
          packager="org.jpos.iso.packager.GenericPackager">
     <property name="packager-config" value="cfg/fdr.xml" />
     <property name="host" value="201.111.11.177" />
     <property name="port" value="21000" />
   </channel>
   <in>fdr-send</in>
   <out>fdr-receive</out>
   <reconnect-delay>10000</reconnect-delay>
   </channel-adaptor>
   
   
4. Configure MUX XML files. Here's an example:
   
   <mux class="org.jpos.q2.iso.QMUX" logger="Q2" name="fdr-mux">
   <in>fdr-receive</in>
   <out>fdr-send</out>
   <ready>fdr.ready fdr1.ready</ready>
   <unhandled>fdr-unhandled</unhandled>
   </mux>
   
   
5. Configure Logon Manager XML files.  Here's an example:
   
   <fdr-logon-mgr class="org.jpos.fdr.LogonManager" logger="Q2">
   <property name="persistent-space" value="jdbm:fdrlogon:log/fdrlogon" />
   <property name="mux"            value="fdr-mux" />
   <property name="channel-ready"  value="fdr.ready" />
   <property name="timeout"        value="900000" />
   <property name="echo-interval"  value="600000" />
   <property name="logon-interval" value="43200000" />
   <property name="pseudo-tid"     value="00999988" />
   <property name="pseudo-mid"     value="000123456789012" />
   <property name="sm"             value="Thales" />
   <property file="cfg/keys.cfg" />
   <property name="initial-delay"  value="5000" />
   </fdr-logon-mgr>
   
   
6. Configure System Monitor XML files (places channel entries into system’s status table for visual monitoring).   Here's an example:
   
   <channel-monitor name='fdr0-monitor' class='org.jpos.ee.status.Monitor' logger='Q2'>
   <monitor id="FDR1 FDR Data Center A 01" delay='10000' period='15000'>
     <class>org.jpos.ee.ChannelMonitor</class>
     <property name='channel' value='fdr' />
   </monitor>
   </channel-monitor>
   
   
7. Configure Store and Forward (‘SAF’) XML files (if applicable).  Here's an example:
   
   <saf name='saf' logger='Q2' realm='saf' class='org.jpos.saf.SAF'>
   <property name='space' value='jdbm:saf' />
   <property name='mux' value='fdr-mux' />
   <property name='flag-retransmissions' value='no'>
     if MTI is in list, messages would be retransmitted as xxx1
   </property>
   <property name='initial-delay' value='60000' />
   <property name='inter-message-delay' value='1000' />
   <property name='wait-for-response' value='60000' />
   <property name='max-retransmissions' value='1000' />
   <property name='expire-after' value='86400'>
     in seconds
   </property>
   <property name='valid-response-codes' value='*' />
   <property name='retry-response-codes' value='91,NL,NM,N8,CE' />
   </saf>
   
   
8. Create external-to-internal Result Code mapping table.
   
9. Write Logon Manager (brief code to handle 0800-level Network message exchange).  Here's a snippet from a program that does that:
   
       private ISOMsg createMsg (String msgType) throws ISOException {
           long traceNumber = SpaceUtil.nextLong (psp, TRACE) % 1000000;
           ISOMsg m = new ISOMsg ("0800");
           m.set (7, ISODate.getDateTime (new Date()));
           m.set (11, ISOUtil.zeropad (Long.toString (traceNumber), 6));
           m.set (70, msgType);
           return m;
   
   
10. Write endpoint-dependent “ISO Request” extension of your base “ISORequest” program (typically a short program to cover deviations from ISO standards and endpoint-specific field-level setting and/or unsetting.  Here's a snippet from a program that does that:
    
            if ("0100".equals (m.getMTI())) {
                m.unset (12);
                m.unset (13);
                // field 59 - zip code
                Store store = (Store) ctx.tget (STORE);
                String zip = "";
                if (store != null && store.getZip() != null)
                    zip = store.getZip().trim();
                m.set (59, padzip (zip, 9));
    
    
11.  Add new transaction routing participants to the Transaction Manager.

NOTE: All examples included therein (above) aren't intended to constitute a 'full' solution.  In each case, I've included it to give you some insight as to what the step entails.

For more details, I suggest you buy a copy of the jPOS Programmer's Guide.  It's a great investment.  Take care to follow that link and not go running to accidentally encounter the similarly named JavaPOS Programmer's Guide.  jPOS and JavaPOS are NOT THE SAME PROJECT (this is the source of a lot of confusion).

Comments

[Jeretyp]

Very good site. Thank you!!!
I'm Mika, new here!
See you soon!