ISO8583 Connector Guide

Introduction

ISO 8583 is an international standard for financial transaction card-originated interchange messaging. It is the International Organization for Standardization standard for systems that exchange electronic transactions initiated by cardholders using payment cards.

Create an ISO8583 Module and Assets

1. First, create an ISO 8583 module.
2. Second, test the connection to the remote ISO8583 server.
3. Third, create a JSON-based ISO8583 asset.
4. Finally, test the created asset by sending a test query to the remote ISO8583 data source.

Step 1. Create an ISO8583 module

First, create the ISO8583 module.

>ol create module module-iso8583 --connector iso8583

$ol create module module-iso8583 --connector iso8583

Step 2. Test the connection to the remote ISO8583 server

Run the ol test connection command to verify that the connection properties are correct and hence that the ISO8583 server on the remote data source is accessible.

1. Navigate to the module folder.
   WindowsmacOS

   >cd module-iso8583
   

   $cd module-iso8583
   

2. From under the module directory, display the help menu of the ol test connection command to review the ISO8583 connector connection properties.

     --verbose                  Enables verbose mode
     --verbose-debug            Enables debug mode
     --verbose-trace            Enables trace mode
     --host TEXT                Specify host (default: localhost)
     --port TEXT                Specify port (default: 5000)
     --network-mgt-enable TEXT  Specify network mgt enable (default: true)
     --timeout TEXT             Specify timeout (default: 30000)
     --max-timeouts TEXT        Specify max timeouts (default: 10)
     --wait-down TEXT           Specify wait down (default: 60000)
     --packager TEXT            Specify packager (default: base24.xml)
     --iso-header TEXT          Specify ISO header
     --depending-on-mode TEXT   Specify depending on mode (default: true)
     --channel TEXT             Specify channel[BASE24, RAW, ASCII] (default: BASE24)
     --pool.enable TEXT         (default: true)
     --pool.max-size TEXT       (default: 5)
     --pool.min-size TEXT       (default: 0)
     --profile TEXT             Configuration profile
     -h, --help                 Show this message and exit
   

3. Log in to our artifactory docker if necessary and run this container:

   docker run -p 5000:5000 openlegacy-registry.jfrog.io/jpos
   

4. Run the ol test connection command and verify that the connection succeeded.

module-iso8583>ol test connection
DONE
Test connection succeeded

module-iso8583$ol test connection --host iso8583.openlegacy.com
DONE
Test connection succeeded

Step 3. Add an asset to the ISO8583 module

After verifying the connection parameters, you can create an ISO8583 asset by executing the ol add command. The command receives the SQL query statement and extracts the SELECT column names and data types. The connector uses this data to compose the input metadata parameters of the asset. Next, the connector applies the query statement on the ISO8583 and analyses the returned result set to compose the asset output metadata parameters.

1. Review the properties of ol add command.

   WindowsmacOS

   m-iso8583>ol add --help
   

   m-iso8583$ol add --help
   

2. The ol add help menu displays the connector property list.

   Usage: ol add [OPTIONS]
   
     Add Asset to Module metadata
   
   Options:
     --verbose                  Enables verbose mode
     --verbose-debug            Enables debug mode
     --verbose-trace            Enables trace mode
     --additional VALUE         Additional properties
     --name TEXT                Specify asset name (required)
     --version TEXT             Specify version[_1987, _1993, _2003] (default: _1987)
     --class TEXT               Specify class[AUTHORIZATION, FINANCIAL, FILE_ACTIONS, REVERSAL_AND_CHARGEBACK, RECONCILIATION, ADMINISTRATIVE,
                                FEE_COLLECTION, NETWORK_MANAGEMENT] (required)
     --function TEXT            Specify function[REQUEST, REQUEST_RESPONSE, ADVICE, ADVICE_RESPONSE, NOTIFICATION, NOTIFICATION_ACKNOWLEDGEMENT,
                                INSTRUCTION, INSTRUCTION_ACKNOWLEDGEMENT, RESERVED_FOR_ISO_USE] (required)
     --origin TEXT              Specify origin[ACQUIRER, ACQUIRER_REPEAT, ISSUER, ISSUER_REPEAT, OTHER, OTHER_REPEAT] (required)
     --asset-iso-header TEXT    Specify asset IsoHeaader
     --host TEXT                Specify host (default: localhost)
     --port TEXT                Specify port (default: 5000)
     --network-mgt-enable TEXT  Specify network mgt enable (default: true)
     --timeout TEXT             Specify timeout (default: 30000)
     --max-timeouts TEXT        Specify max timeouts (default: 10)
     --wait-down TEXT           Specify wait down (default: 60000)
     --packager TEXT            Specify packager (default: base24.xml)
     --iso-header TEXT          Specify ISO header
     --depending-on-mode TEXT   Specify depending on mode (default: true)
     --channel TEXT             Specify channel[BASE24, RAW, ASCII] (default: BASE24)
     --pool.enable TEXT         (default: true)
     --pool.max-size TEXT       (default: 5)
     --pool.min-size TEXT       (default: 0)
     --profile TEXT             Configuration profile
     -h, --help                 Show this message and exit
   

3. Run the ol add command to create an asset:

   WindowsmacOS

   m-iso8583>ol add --name test --class FILE_ACTIONS --function REQUEST --origin ACQUIRER --asset-iso-header "ISO123456789"
   DONE
   Asset 'test' created in module m-iso8583.
   To test the asset, fill test data in 'assets/test/test_data/case-1/in.json'
   and run 'ol test asset test'
   

   m-iso8583$ol add --name test --class FILE_ACTIONS --function REQUEST --origin ACQUIRER --asset-iso-header "ISO123456789"
   DONE
   Asset 'test' created in module m-iso8583.
   To test the asset, fill test data in 'assets/test/test_data/case-1/in.json'
   and run 'ol test asset test'
   
   

   Step 4. Test the ISO8583 asset

   After adding the asset, you can test it by executing the ol test asset command to verify that you can request and receive actual business data from the data source.

1. From your module folder root go to assets/test/test_data/case1/.

module-iso8583>cd assets/test/test_data/case1/

module-iso8583$cd assets/test/test_data/case1/

2. To view and edit the test input data open in.json. in.json contains the information sent to the remote business operation. It consists of the input keys and values that the business operation requires. For example:

{
  "p1SecondBitmap": "C2200000000180140000002008000000",
  "p2PrimaryAccountNumberPAN": "160145000100343405",
  "p7TransmissionDateTime": "0622125214",
  "p11SystemTraceAuditNumberSTAN": 70839,
  "p48AdditionalDataPrivate": "045000BCA 00000000000000000000010000000000123456",
  "p49CurrencyCodeTransaction": 360,
  "p60ReservedNational": "05801010000PRO100000000000000NY000000000000USTA00000000000000",
  "p62ReservedPrivate": "001 ",
  "p91FileUpdateCode": "2"
}

3. Now you are ready to run ol test asset.

module-iso8583>ol test asset test

module-iso8583$ol test asset test

4. It should return something like:

   {
     "p0MessageTypeIndicator" : "0210",
     "p2PrimaryAccountNumberPAN" : "160145000100343405",
     "p7TransmissionDateTime" : "0622125214",
     "p11SystemTraceAuditNumberSTAN" : 70839,
     "p39ResponseCode" : "00",
     "p48AdditionalDataPrivate" : "045000BCA 00000000000000000000010000000000123456",
     "p49CurrencyCodeTransaction" : 360,
     "p60ReservedNational" : "05801010000PRO100000000000000NY000000000000USTA00000000000000",
     "p62ReservedPrivate" : "001",
     "p91FileUpdateCode" : "2"
   }