{"id":13544897,"url":"https://github.com/kpavlov/jreactive-8583","last_synced_at":"2025-05-15T19:05:12.679Z","repository":{"id":41461619,"uuid":"38583413","full_name":"kpavlov/jreactive-8583","owner":"kpavlov","description":"Kotlin/Java Client \u0026 Server for ISO8583 \u0026 Netty","archived":false,"fork":false,"pushed_at":"2025-05-15T16:53:47.000Z","size":538,"stargazers_count":328,"open_issues_count":17,"forks_count":149,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-05-15T19:04:26.789Z","etag":null,"topics":["client-library","iso8583","iso8583-java","iso8583-kotlin","java","jpos","kotlin","library","netty","pan","pos"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpavlov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["kpavlov"]}},"created_at":"2015-07-05T20:44:44.000Z","updated_at":"2025-05-15T16:53:51.000Z","dependencies_parsed_at":"2024-01-02T09:31:55.451Z","dependency_job_id":"2aeb8977-8454-418a-9f5e-b3958fecd619","html_url":"https://github.com/kpavlov/jreactive-8583","commit_stats":{"total_commits":254,"total_committers":11,"mean_commits":23.09090909090909,"dds":"0.29527559055118113","last_synced_commit":"a35a40d159e98adde08ffea16ea0d3436f6bdbf4"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fjreactive-8583","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fjreactive-8583/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fjreactive-8583/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fjreactive-8583/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpavlov","download_url":"https://codeload.github.com/kpavlov/jreactive-8583/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254404357,"owners_count":22065641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-library","iso8583","iso8583-java","iso8583-kotlin","java","jpos","kotlin","library","netty","pan","pos"],"created_at":"2024-08-01T11:00:54.714Z","updated_at":"2025-05-15T19:05:12.621Z","avatar_url":"https://github.com/kpavlov.png","language":"Kotlin","funding_links":["https://github.com/sponsors/kpavlov","https://buymeacoffee.com/mailsk"],"categories":["Banking Infrastructure"],"sub_categories":[],"readme":"# JReactive-8583\n\nFree ISO8583 Connector for JDK (Netty)\n\n[![Buy me a Coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://buymeacoffee.com/mailsk)\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.kpavlov.jreactive8583/netty-iso8583.svg?label=Maven%20Central)](https://repo1.maven.org/maven2/com/github/kpavlov/jreactive8583/netty-iso8583/)\n[![Build Status](https://github.com/kpavlov/jreactive-8583/actions/workflows/gradle.yml/badge.svg)](https://github.com/kpavlov/jreactive-8583/actions/workflows/gradle.yml)\n![Libraries.io for GitHub](https://img.shields.io/librariesio/github/kpavlov/jreactive-8583.svg?maxAge=2592000)\n[![Maintainability](https://api.codeclimate.com/v1/badges/56e9f30962b0cbd97ed7/maintainability)](https://codeclimate.com/github/kpavlov/jreactive-8583/maintainability)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/56d83582f4564db9bfee15b0309ee0b5)](https://app.codacy.com/gh/kpavlov/jreactive-8583/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\n## Motivation\n\n1. [jPOS][jpos] library is not free for commercial use.\n2. [j8583][j8583] is free but does not offer network client\n\nSolution: **\"J-Reactive-8583\"** ISO8583 Client and Server built on top of excellent [Netty][netty] asynchronous messaging framework with the help of [j8583][j8583] for encoding/decoding. It is distributed under Apache License 2.0.\n\n## Supported Features\n\n* Client and Server endpoints.\n* Java 11+\n* Support ISO8583 messages using [j8583][j8583] library.\n* Customizable [ISO MessageFactory][j8583-message-factory].\n* Automatic responding to Echo messages.\n* Automatic client reconnection.\n* Secure [message logger](https://github.com/kpavlov/jreactive-8583/blob/master/src/main/java/com/github/kpavlov/jreactive8583/netty/pipeline/IsoMessageLoggingHandler.java): mask PAN and track data or any other field (customizable). Optionally prints field descriptions.\n * Configurable netty [Bootstrap](https://github.com/netty/netty/blob/master/transport/src/main/java/io/netty/bootstrap/Bootstrap.java) and [ChannelPipeline](https://github.com/netty/netty/blob/master/transport/src/main/java/io/netty/channel/ChannelPipeline.java)\n\n## ISO8583 TCP/IP Transport\n\nFor data transmission TCP/IP uses sessions.\nEach session is a bi-directional data stream.\nThe protocol uses a single TCP/IP session to transfer data between hosts in both directions.\n\nThe continuous TCP/IP data stream is split into frames.\nEach [ISO8583][iso8583] message is sent in a separate frame.\n\nA Frame consists of an N-byte length header and message body.\nUsually, N==2.\nThe header contains the length of the following message.\nThe high byte of value is transmitted first, and the low byte of value is transmitted second.\n\n| N bytes            | M bytes            |\n| ------------------ | ------------------ |\n| Message Length = M | ISO–8583 Message   |\n\n# Getting Started\n\nAdd dependency to your project:\n\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ecom.github.kpavlov.jreactive8583\u003c/groupId\u003e\n            \u003cartifactId\u003enetty-iso8583\u003c/artifactId\u003e\n            \u003cversion\u003e${LATEST_VERSION}\u003c/version\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\nNow you may use ISO8583 client or server in your code.\n\n## Creating and Using ISO-8583 Client\n\nThe minimal client workflow includes:\n\n~~~java\nvar messageFactory = new J8583MessageFactory\u003c\u003e(ISO8583Version.V1987, MessageOrigin.OTHER);// [1]\nIso8583Client\u003cIsoMessage\u003e client = new Iso8583Client\u003c\u003e(messageFactory);// [2]\n\nclient.addMessageListener(new IsoMessageListener\u003cIsoMessage\u003e() { // [3]\n    ...\n});\nclient.getConfiguration().replyOnError(true);// [4]\nclient.init();// [5]\n\nclient.connect(host, port);// [6]\nif (client.isConnected()) { // [7]\n\n    IsoMessage message = messageFactory.newMessage(...);\n    ...\n    client.sendAsync(message);// [8]\n    // or\n    client.send(message);// [9]\n    // or\n    client.send(message, 1, TimeUnit.SECONDS);// [10]\n}\n\n...\nclient.shutdown();// [11]\n~~~\n\n1. First you need to create a `MessageFactory`. You MUST specify a role of your client for\n   originated messages, e.g. `ACQUIRER`, `ISSUER` or `OTHER`.\n2. Then you create a [`Iso8583Client`][Iso8583Client] providing `MessageFactory` and,\n   optionally, `SocketAddress`\n3. Add one or more custom [`IsoMessageListener`][IsoMessageListener]s to handle `IsoMessage`s.\n4. Configure the client. You may omit this step if you're fine with default configuration.\n5. Initialize a client. Now it is ready to connect.\n6. Establish a connection. By default, if connection will is lost, it reconnects automatically. You\n   may disable this behaviour or change _reconnectInterval_.\n7. Verify that connection is established\n8. Send `IsoMessage` asynchronously\n9. Send `IsoMessage` synchronously\n10. Send `IsoMessage` synchronously with timeout support\n11. Disconnect when you're done.\n\n## Creating and Using ISO-8583 Server\n\nTypical server workflow includes:\n\n~~~java\nvar messageFactory = new J8583MessageFactory\u003c\u003e(ConfigParser.createDefault(), ISO8583Version.V1987, MessageOrigin.ACQUIRER);// [1]\nIso8583Server\u003cIsoMessage\u003e server = new Iso8583Server\u003c\u003e(port, messageFactory);// [2]\n\nserver.addMessageListener(new IsoMessageListener\u003cIsoMessage\u003e() { // [3]\n    ...\n});\nserver.getConfiguration().replyOnError(true);// [4]\nserver.init();// [5]\n\nserver.start();// [6]\nif (server.isStarted()) { // [7]\n    ...\n}\n\n...\nserver.shutdown();// [8]\n~~~\n\n1. First you need to create a `MessageFactory`. You MUST specify a role of your server for\n   originated messages, e.g. `ACQUIRER`, `ISSUER` or `OTHER`.\n2. Then you create a [`Iso8583Server`][Iso8583Server] providing `MessageFactory` and port to bind to\n3. Add one or more custom [`IsoMessageListener`][IsoMessageListener]s to handle `IsoMessage`s.\n4. Configure the server. You may omit this step if you're fine with default configuration.\n5. Initialize a server. Now it is ready to start.\n6. Start server. Now it is ready to accept client connections.\n7. Verify that the server is started\n9. Shutdown server when you're done.\n\n## Logging\n\nDefault [`IsoMessageLoggingHandler`][IsoMessageLoggingHandler] may produce output like:\n\n    312 [nioEventLoopGroup-5-1] DEBUG IsoMessageLoggingHandler - [id: 0xa72cc005, /127.0.0.1:50853 =\u003e /127.0.0.1:9876] MTI: 0x0200\n      2: [Primary account number (PAN):NUMERIC(19)] = '000400*********0002'\n      3: [Processing code:NUMERIC(6)] = '650000'\n      7: [Transmission date \u0026 time:DATE10(10)] = '0720233443'\n      11: [System trace audit number:NUMERIC(6)] = '483248'\n      32: [Acquiring institution identification code:LLVAR(3)] = '456'\n      35: [Track 2 data:LLVAR(17)] = '***'\n      43: [Card acceptor name/location (1-23 address 24-36 city 37-38 state 39-40 country):ALPHA(40)] = 'SOLABTEST TEST-3 DF MX                  '\n      49: [Currency code, transaction:ALPHA(3)] = '484'\n      60: [Reserved national:LLLVAR(3)] = 'foo'\n      61: [Reserved private:LLLVAR(5)] = '1234P'\n      100: [Receiving institution identification code:LLVAR(3)] = '999'\n      102: [Account identification 1:LLVAR(4)] = 'ABCD'\n\nUsing client or server configuration\n\nYou may:\n\n- enable message logging. As of 0.2.2 logging is disabled by default (#50).\n- enable and disable printing of sensitive information, like PAN\n- customize which fields should be masked in logs\n- enable and disable printing field descriptions\n- customize tcp frame length field length\n- customize [ISO 8583 version](https://en.wikipedia.org/wiki/ISO_8583#ISO_8583_version)\n\nSee\n[ConnectorConfiguration](./src/main/java/com/github/kpavlov/jreactive8583/ConnectorConfiguration.java)\n,\n[ServerConfiguration](./src/main/java/com/github/kpavlov/jreactive8583/server/ServerConfiguration.java)\nand\n[ClientConfiguration](./src/main/java/com/github/kpavlov/jreactive8583/client/ClientConfiguration.java)\n.\n\n---\nFor frequently asked questions check the [FAQ](https://github.com/kpavlov/jreactive-8583/wiki/FAQ)\npage.\n\n## Sequence Diagram\n\nMessage processing is described in the following diagram:\n\n![Sequence Diagram](docs/sequence.svg)\n\n## ISO 8583 Links\n\n- Beginner's guide: http://www.lytsing.org/downloads/iso8583.pdf\n- Introduction to ISO8583: http://www.codeproject.com/Articles/100084/Introduction-to-ISO-8583\n- NPM package for Packing and unpacking ISO 8583 messages: https://www.npmjs.com/package/iso-8583\n- [ISO 8583 wiki page](https://en.wikipedia.org/wiki/ISO_8583)\n\n[iso8583]: https://en.wikipedia.org/wiki/ISO_8583\n\n[iso-examples]: https://github.com/beckerdo/ISO-8583-Examples \"Some payments processing examples\"\n[j8583-example]: https://krishnarag.wordpress.com/2014/06/18/iso-8583-j8583-java-library/\n[j8583]: https://bitbucket.org/chochos/j8583 \"Java implementation of the ISO8583 protocol.\"\n[j8583-message-factory]: https://github.com/chochos/j8583/blob/master/src/main/java/com/solab/iso8583/IsoMessage.java\n[jpos]: http://jpos.org\n[netty]: https://netty.io\n\n[Iso8583Client]: https://github.com/kpavlov/jreactive-8583/blob/master/src/main/java/com/github/kpavlov/jreactive8583/client/Iso8583Client.java\n[Iso8583Server]: https://github.com/kpavlov/jreactive-8583/blob/master/src/main/java/com/github/kpavlov/jreactive8583/server/Iso8583Server.java\n[IsoMessageListener]: https://github.com/kpavlov/jreactive-8583/blob/master/src/main/java/com/github/kpavlov/jreactive8583/IsoMessageListener.java\n[IsoMessageLoggingHandler]: https://github.com/kpavlov/jreactive-8583/blob/master/src/main/java/com/github/kpavlov/jreactive8583/netty/pipeline/IsoMessageLoggingHandler.java\n\n# [Contributors](https://github.com/kpavlov/jreactive-8583/graphs/contributors)\n\n![](https://contrib.rocks/image?repo=kpavlov/jreactive-8583)\n\n\u003csmall \u003eMade with [contrib.rocks](https://contrib.rocks).\u003c/small\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpavlov%2Fjreactive-8583","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpavlov%2Fjreactive-8583","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpavlov%2Fjreactive-8583/lists"}