Free ISO8583 Java Connector
Solution: "J-Reactive-8583" ISO8583 Client and Server built on top of excellent Netty asynchronous messaging framework with the help of j8583 for encoding/decoding. It is distributed under Apache License 2.0.
- Client and Server endpoints.
- Support ISO8583 messages using j8583 library.
- Customizable ISO MessageFactory.
- Automatic responding to Echo messages.
- Automatic client reconnection.
- Secure message logger: mask PAN and track data or any any other field (customizable). Optionally prints field descriptions.
- Configurable netty Bootstrap and ChannelPipeline
For data transmission TCP/IP uses sessions. Each session is a bi-directional data stream. The protocol uses a single TCP/IP session to transfer data between hosts in both directions.
The continuous TCP/IP data stream is split into frames. Each ISO8583 message is sent in a separate frame.
A Frame consists of a N-byte length header and a message body. Usually, N==2. The header contains the length of the following message. The high byte of value is transmitted first, and the low byte of value is transmitted second.
N bytes | M bytes |
---|---|
Message Length = M | ISO–8583 Message |
First, you need to download latest release or clone this repository and build artifact with maven manually.
Then add dependency to your project:
<dependencies>
<dependency>
<groupId>com.github.kpavlov.jreactive8583</groupId>
<artifactId>netty-iso8583</artifactId>
<version>0.2.2</version>
</dependency>
<dependencies>
Now you may use ISO8583 client or server in your code.
The minimal client workflow includes:
MessageFactory<IsoMessage> messageFactory = ConfigParser.createDefault();// [1]
Iso8583Client<IsoMessage> client = new Iso8583Client<>(messageFactory);// [2]
client.addMessageListener(new IsoMessageListener<IsoMessage>() { // [3]
...
});
client.getConfiguration().replyOnError(true);// [4]
client.init();// [5]
client.connect(host, port);// [6]
if (client.isConnected()) { // [7]
IsoMessage message = messageFactory.newMessage(...);
...
client.sendAsync(message);// [8]
// or
client.send(message);// [9]
// or
client.send(message, 1, TimeUnit.SECONDS);// [10]
}
...
client.shutdown();// [11]
- First you need to create a
MessageFactory
- Then you create a
Iso8583Client
providingMessageFactory
and, optionally,SocketAddress
- Add one or more custom
IsoMessageListener
s to handleIsoMessage
s. - Configure the client. You may omit this step if you're fine with default configuration.
- Initialize client. Now it is ready to connect.
- Establish a connection. By default, if connection will is lost, it reconnects automatically. You may disable this behaviour or change reconnectInterval.
- Verify that connection is established
- Send
IsoMessage
asynchronously - Send
IsoMessage
synchronously - Send
IsoMessage
synchronously with timeout support - Disconnect when you're done.
Typical server workflow includes:
MessageFactory<IsoMessage> messageFactory = ConfigParser.createDefault();// [1]
Iso8583Server<IsoMessage> server = new Iso8583Server<>(port, messageFactory);// [2]
server.addMessageListener(new IsoMessageListener<IsoMessage>() { // [3]
...
});
server.getConfiguration().replyOnError(true);// [4]
server.init();// [5]
server.start();// [6]
if (server.isStarted()) { // [7]
...
}
...
server.shutdown();// [8]
- First you need to create a
MessageFactory
- Then you create a
Iso8583Server
providingMessageFactory
and port to bind to - Add one or more custom
IsoMessageListener
s to handleIsoMessage
s. - Configure the server. You may omit this step if you're fine with default configuration.
- Initialize server. Now it is ready to start.
- Start server. Now it is ready to accept client connections.
- Verify that the server is started
- Shutdown server when you're done.
Default IsoMessageLoggingHandler
may produce output like:
312 [nioEventLoopGroup-5-1] DEBUG IsoMessageLoggingHandler - [id: 0xa72cc005, /127.0.0.1:50853 => /127.0.0.1:9876] MTI: 0x0200
2: [Primary account number (PAN):NUMERIC(19)] = '000400*********0002'
3: [Processing code:NUMERIC(6)] = '650000'
7: [Transmission date & time:DATE10(10)] = '0720233443'
11: [System trace audit number:NUMERIC(6)] = '483248'
32: [Acquiring institution identification code:LLVAR(3)] = '456'
35: [Track 2 data:LLVAR(17)] = '***'
43: [Card acceptor name/location (1-23 address 24-36 city 37-38 state 39-40 country):ALPHA(40)] = 'SOLABTEST TEST-3 DF MX '
49: [Currency code, transaction:ALPHA(3)] = '484'
60: [Reserved national:LLLVAR(3)] = 'foo'
61: [Reserved private:LLLVAR(5)] = '1234P'
100: [Receiving institution identification code:LLVAR(3)] = '999'
102: [Account identification 1:LLVAR(4)] = 'ABCD'
Using client or server configurationYou may :
- enable and disable printing of sensitive information, like PAN
- customize which fields should be masked in logs
- enable and disable printing field descriptions
You may provide your own logging handler and disable default one by using ConnectorConfiguration.addLoggingHandler(boolean)
method and customizing ChannelPipeline.
For frequently asked questions check the FAQ page.
- Beginner's guide: http://www.lytsing.org/downloads/iso8583.pdf
- Introduction to ISO8583: http://www.codeproject.com/Articles/100084/Introduction-to-ISO-8583
- NPM package for Packing and unpacking ISO 8583 messages: https://www.npmjs.com/package/iso-8583