{"id":13544888,"url":"https://github.com/juks/iso-8583-socket-queue","last_synced_at":"2025-04-02T15:30:48.252Z","repository":{"id":36741126,"uuid":"41047725","full_name":"juks/iso-8583-socket-queue","owner":"juks","description":"ISO 8583 gateway","archived":false,"fork":false,"pushed_at":"2023-03-01T11:05:21.000Z","size":269,"stargazers_count":195,"open_issues_count":10,"forks_count":112,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-11-03T12:31:47.510Z","etag":null,"topics":["8583","acquiring","iso-8583","iso8583","mpos","payment-gateway","payment-integration","smartvista"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-08-19T17:00:43.000Z","updated_at":"2024-09-16T06:55:59.000Z","dependencies_parsed_at":"2024-01-16T17:02:56.179Z","dependency_job_id":"f13a0552-3a59-4193-8b06-a3be968a4fc5","html_url":"https://github.com/juks/iso-8583-socket-queue","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juks%2Fiso-8583-socket-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juks%2Fiso-8583-socket-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juks%2Fiso-8583-socket-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juks%2Fiso-8583-socket-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juks","download_url":"https://codeload.github.com/juks/iso-8583-socket-queue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246841537,"owners_count":20842609,"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":["8583","acquiring","iso-8583","iso8583","mpos","payment-gateway","payment-integration","smartvista"],"created_at":"2024-08-01T11:00:54.639Z","updated_at":"2025-04-02T15:30:47.949Z","avatar_url":"https://github.com/juks.png","language":"JavaScript","funding_links":[],"categories":["Banking Infrastructure"],"sub_categories":[],"readme":"# SocketQueue\nThis is a free ISO 8583 gateway (bridge) implementation for banking/fintech POS systems communication. The project is powered by Node.js (https://nodejs.org/).\n\n## The Idea\nSocketQueue acts as a gateway between bank ISO 8583 system and customer applications/processes that need to talk to it. The service keeps one \"host-to-host\" connection with the bank processing host, that is used to transfer data, sent by multiple local clients in various representations. In terms of POS processing systems \"host-to-host\" connection means all the data is sent and received via single full-duplex socket asynchronously. \n\nThe recieved data is assigned to appropriate sender using the TID (Terminal Id) and STAN (System Trace Audit Number). If there are two clients sending payments transactions using the same TID, the second packet will be queued until the first one is processed or timed out. This is not normal/legal operation mode in terms of International Payments Systems, but some small fintech startups may have to accept it due to the greediness of some of the acquiring banks.\n\n\u003cpre\u003e\n                                        +---------------+\n   +-------------------+                |               | \u003c--JSON 8583--\u003e POS HTTP client\n   | Bank POS ISO HOST | \u003c--ISO 8583--\u003e |  SocketQueue  | \u003c--ISO 8583---\u003e POS binary client\n   +-------------------+                |               | \u003c--HTTP HEX---\u003e POS HTTP client\n                                        +---------------+\n\u003c/pre\u003e\n                          \n## Features\n* Multiplexing connection manager;\n* Modern and friendly JSON interface to aged or unfriendly ISO 8583 processing hosts;\n* Host-to-Host on the left hand (one permanent TCP connection), Host‑to‑POS (many TCP connections) on the right;\n* Supports both binary ISO 8583 and JSON over HTTP operation modes at the same time;\n* ISO 8583 validation, ISO 8583 values padding;\n* Customizable ISO 8583 syntax;\n* Safe data/events logger (console, files, LogStash);\n* Message queue;\n* TID queueing (wait for busy TID);\n* Auto-reversal implementation;\n* Socket Bank (emulates the ISO host);\n* Test clients (self test mode);\n* Stats Server (current transactions amount, MTI stats);\n* Solves the SmartVista weird transactions mishandling;\n* Lighweight, PCI-DSS friendly, reliable, event based. Hundreds of concurrent connections/transactions at a time;\n* Bonus: prevents remote ISO hosts crashes caused by PCI-DSS automated security scanning procedures.\n \n## Installation (works both for Linux and Windows)\n* In case you do not have node.js installed, follow the installation instructions at https://nodejs.org/en/download/\n\n* Install git client and clone the repository:  \n    _git clone https://github.com/juks/iso-8583-socket-queue_\n\n* Install extra modules:  \n    _cd iso-8583-socket-queue_  \n    _npm install_\n\n  Done!\n  \nSocketQueue is tested in production to work for months, processing thousands of transactions a day without crashes or memory leaks. I recommend running it under the Supervisor utility https://github.com/Supervisor/supervisor.\nSample supervisor config may look like:\n\n    [program:socketqueue]\n    command=node ./socketQueue.js -c config.json\n    directory=/path/to/socketqueue\n    autostart=true\n    autorestart=true\n    startsecs=5\n    startretries=3\n    stopsignal=TERM\n    stopwaitsecs=10\n\n## Basic Usage\nTo get familiar with all the command line and configuration file parameters available, run SocketQueue with _--help_ option:\n\n    $ node socketQueue.js --help\n\nTo establish the gateway to remote ISO host on 10.0.0.1:5000, that accepts binary ISO 8583 messages, run the module as following:  \n\n    $ node socketQueue.js --upstreamHost=10.0.0.1 --upstreamPort=5000 --listenPort=2014\n    \nTo add verbosity and log data into a file use:  \n\n    $ node socketQueue.js --upstreamHost=10.0.0.1 --upstreamPort=5000 --listenPort=2014 --vv --logFile=log.txt\n    \nTo make it silent in console, use _--silent_ option:  \n\n    $ node socketQueue.js --upstreamHost=10.0.0.1 --upstreamPort=5000 --listenPort=2014 --vv --logFile=log.txt --silent\n    \nYou may keep all the options inside the configuration file, and run the SocketQueue just like that:\n\n    $ node socketQueue.js --c=config.json\n    \nWhere config.json contains:\n\n```json\n{\n    \"upstreamHost\":    \"10.0.0.1\",\n    \"upstreamPort\":    5000,\n    \"listenPort\":      2014,\n    \"vv\":              true,\n    \"logFile\":         \"log.txt\"\n}\n```\n## Binary ISO 8583 service\nSocketQueue provides the service for the POS transactions, sent as ISO 8583 messages. Each valid ISO 8583 message, sent by client is sent to ISO host. Each ISO host response is sent back to the client as ISO 8583 message. To run ISO 8583 gateway on certain port, use the _--listenPort_ parameter.\n\nEach message consists of three parts: the MTI (Message Type Indicator), Binary Mask (lists the fields, being sent) and the fields values. You may find more detailed sytax description on Wiki page https://en.wikipedia.org/wiki/ISO_8583\n\n## HTTP JSON Service\nSocketQueue understands the ISO 8583 transactions, sent as JSON object. Each valid message is converted to ISO 8583 string, values are padded where necessary. The message then goes to ISO host. The ISO host responses are converted back to JSON object and sent back to clients.\n\nTo run the HTTP server use _--listenHttpPort_ option with the port number to listen on.\n\n    $ node socketQueue.js --upstreamHost=10.0.0.1 --upstreamPort=5000 --listenHttpPort=8080 --vv --logFile=log.txt\n\nWhen it is running on port 8080, you can test it like this with the \"purchase\" EMV transcation data:\n\n```bash\n$ curl -H \"Content-Type: application/json\" -X POST -d '{ \"0\": \"0200\",  \"3\": \"0\",  \"4\": 1000,  \"7\": \"0818160933\",  \"11\": 618160,  \"12\": \"150820130600\",  \"22\": \"056\",  \"24\": \"200\",  \"25\": \"00\",  \"35\": \"4850781234567891=19082012232800000037\",  \"41\": 992468,  \"42\": 124642124643,  \"49\": \"810\",  \"55\": \"9f2608571f1e10d4fa4aac9f2701809f100706010a03a4b8029f37045bb074729f3602000c950500800010009a031508189c01009f02060000000010005f2a02064382023c009f1a0206439f03060000000000009f3303e0f0c89f34034403029f3501229f1e0835313230323831358407a00000000310109f41030000565f340101\" }' http://localhost:8080\n```\n\nIn case of success you will get the following response\n\n```json\n{\n   \"result\":{\n      \"0\": \"0210\",\n      \"1\": \"723005802ec08200\",\n      \"2\": \"4850780000478123\",\n      \"3\": 0,\n      \"4\": 1000,\n      \"7\": \"0820130546\",\n      \"11\": \"618160\",\n      \"12\": \"150820130600\",\n      \"22\": \"056\",\n      \"24\": 200,\n      \"25\": 0,\n      \"35\": \"4850781234567891=19082012232800000037\",\n      \"37\": \"708981921851\",\n      \"38\": \"VaHYUU\",\n      \"39\": 0,\n      \"41\": \"00992468\",\n      \"42\": \"000124642124643\",\n      \"49\": 643,\n      \"55\": \"9f2608571f1e10d4fa4aac9f2701809f100706010a03a4b8029f37045bb074729f3602000c950500800010009a031508189c01009f02060000000010005f2a02064382023c009f1a0206439f03060000000000009f3303e0f0c89f34034403029f3501229f1e0835313230323831358407a00000000310109f41030000565f340101\"\n   },\n   \"errors\":[]\n}\n```\n\nIn case you have verbose output or logging enabled, the following messages will be logged (test performed using the local echo server):\n\n```\n2015-08-31 18:22:57 - info: New HTTP socket                         \n2015-08-31 18:22:57 - info: Client http:127.0.0.1:53578 connected                         \n2015-08-31 18:22:57 - info: Client http:127.0.0.1:53578 sent data                         \n2015-08-31 18:22:57 - verbose: \n\nhttp:127.0.0.1:53578\n================================================================================================\n\n     [Purchase Request]\n\n     Message Type Indicator [0].......................0200\n     Bitmap [1].......................................3230058020c08200\n     Processing Code [3]..............................0\n     Amount, Transaction [4]..........................1000\n     Transmission Date and Time [7]...................0818160933\n     System Trace Audit Number [11]...................618160\n     Time, Local Transaction [12].....................150831182300\n     Pos Entry Mode [22]..............................056 (Card Data Input Mode: \u003cIntegrated circuit card read; CVV data reliable\u003e; Cardholder Auth Method: \u003cSignature Based\u003e)\n     Function Code [24]...............................200\n     Pos Condition Code [25]..........................00\n     Track 2 Data [35]................................485078******7891=19082012232800000037\n     Card Acceptor Terminal Identification [41].......00992468\n     Merchant Id [42].................................000124642124643\n     Currency code, transaction [49]..................643\n     EMV Data [55]....................................9f2608571f1e10d4fa4aac9f2701809f100706010a03a4b8029f37045bb074729f3602000c950500800010009a031508189c01009f02060000000010005f2a02064382023c009f1a0206439f03060000000000009f3303e0f0c89f34034403029f3501229f1e0835313230323831358407a00000000310109f41030000565f340101\n\n================================================================================================\n\n                         \n2015-08-31 18:22:57 - info: Writing to queue http:127.0.0.1:53578 [0]                         \n2015-08-31 18:22:57 - info: New queue item 1                         \n2015-08-31 18:22:57 - info: Processing queue [pending 1 / total 1]                         \n2015-08-31 18:22:57 - info: Upstreaming data for http:127.0.0.1:53578                         \n2015-08-31 18:22:57 - verbose: [02630200...]                         \n2015-08-31 18:22:57 - info: Echo server got data                         \n2015-08-31 18:22:57 - info: Replying to client 00992468                         \n2015-08-31 18:22:57 - info: Echo server sent response                         \n2015-08-31 18:22:57 - info: Got data from ISO-host (306b)                         \n2015-08-31 18:22:57 - verbose: [03020210...]                         \n2015-08-31 18:22:57 - info: Parsed data for http:127.0.0.1:53578                         \n2015-08-31 18:22:57 - verbose: \n\nISO host to http:127.0.0.1:53578\n================================================================================================\n\n     [Purchase Response]\n\n     Message Type Indicator [0].......................0210\n     Bitmap [1].......................................723005802ec08200\n     Primary Account Number [2].......................485078******7891\n     Processing Code [3]..............................0\n     Amount, Transaction [4]..........................1000\n     Transmission Date and Time [7]...................0831182257\n     System Trace Audit Number [11]...................618160\n     Time, Local Transaction [12].....................150831182300\n     Pos Entry Mode [22]..............................056 (Card Data Input Mode: \u003cIntegrated circuit card read; CVV data reliable\u003e; Cardholder Auth Method: \u003cSignature Based\u003e)\n     Function Code [24]...............................200\n     Pos Condition Code [25]..........................0\n     Track 2 Data [35]................................485078******7891=19082012232800000037\n     Retrieval Reference Number [37]..................347408919250\n     Approval code [38]...............................2Ttb0c\n     Response code [39]...............................0 (Successful Transaction)\n     Card Acceptor Terminal Identification [41].......00992468\n     Merchant Id [42].................................000124642124643\n     Currency code, transaction [49]..................643\n     EMV Data [55]....................................9f2608571f1e10d4fa4aac9f2701809f100706010a03a4b8029f37045bb074729f3602000c950500800010009a031508189c01009f02060000000010005f2a02064382023c009f1a0206439f03060000000000009f3303e0f0c89f34034403029f3501229f1e0835313230323831358407a00000000310109f41030000565f340101\n\n================================================================================================\n```\n\nAlso, there is a /raw URL that accepts HEX-encoded data.\n\nHere goes an example for the following message:\n```\n08002220010000800000990000083020354500000183100000001\n```\n\nThat can get transmitted over HTTP as:\n```bash\n$ curl -H \"Content-Type: text/plain\" -X POST -d '303830302220010000c00000303030303030303630373136313730303132333435363030303030313233343536313233353637383930313234353637' http://localhost:8080/raw\n```\n\n## ISO Host Emulation and “Self Test” Clients\nUsing _--echoServerPort_ parameter, you can run the local ISO host emulator that supports basic operations like 800 (echo), 200 (purchase) and 400 (reversal). To emulate the real client connections/requests process you can add the _--testClients_ option. Do not forget to supply it with _--testTargetHost_ and _--testTargetPort_.\n\nThe following example shows two separate instances of SocketQueue running, but you can also stack all parameters in one line and start only one copy.\n\nThe upstream and echo servers two in one:\n\n    $ node socketQueue.js --upstreamHost=localhost --upstreamPort=5000 --listenPort=2014 --vv --echoServerPort=5000\n    \nEmulate 10 clients:\n\n    $ node socketQueue.js --testTargetHost=localhost --testTargetPort=2014 --testClients=10 --vv\n     \nOr you can run only the echo server with so called \"Socket Bank\" onboard:\n\n    $ node socketQueue.js --vv --echoServerPort=5000\n\n## Collecting the Statistics\nThe option _--statServerPort_ enables the statistics module and starts the stat server on given port number, that collects the following statistics of while SocketQueue accepts ISO 8583 transactions:\n\nParameter | Meaning \n--- | ---\n*securedAmount* | sucessful transactions amount minus refund and reversal amount\n*processedAmount* | total transactions amount, including failed transactions\n*refundAmount* | total amount of refund transactions\n*reversalAmount* | total amount of reversal transactions\n*faultStat* | error codes statistics\n*packetCount* | packet count, both total and by each MTI type that was handled during the operation\n\nSo, if stats server is running on port 4000, _telnet 4000_ will give json stats, that may look like this:\n\n```javascript\n{\n   \"securedAmount\":1383554.49,\n   \"processedAmount\":1876911.69,\n   \"refundAmount\":0,\n   \"reversalAmount\":3460,\n   \"faultStat\":{\n      \"5\": 2,\n      \"100\": 7,\n      \"103\": 1,\n      \"116\": 3,\n      \"117\": 1,\n      \"120\": 10\n   },\n   \"packetCount\":{\n      \"total\": 2265,\n      \"0800\": 730,\n      \"0810\": 724,\n      \"0200\": 367,\n      \"0210\": 364,\n      \"0400\": 48,\n      \"0410\": 32\n   }\n}\n```\nThis is just fine to use with Zabbix, Kibana or other monitoring tools.\n\n## Compatibility\nOne can consider SocketQueue to work with SmartVista and OpenWay processing systems.\n\n## Signals\nSocketQueue treats just fine the TERM, INT and HUP signals. It gracefully quits on TERM/INT and resets the stats/reopens log file on HUP signal.\n\n“Graceful quit” means that before quitting:\n* there will be no new connections from POS clients accepted\n* active transactions responses will be delivered\n* given amount of auto-reversal requests (if enabled) will be performed.\n\nTo force process termination at any time, give it a KILL signal.\n\n## ISO 8583 echo host\nThere is a public demo instance of SocketQueue running on the following address:\n* askarov.com:12345 - raw upstream\n* askarov.com:12346 - HTTP JSON upstream\n\nYou can use sample payload to talk to echo host in raw mode:\n```bash\n$ cat ./sample_payloads/sv_800_echo.txt - | nc askarov.com 12345\n```\n\nFor HTTP JSON:\n```bash\n$ curl -H \"Content-Type: application/json\" -X POST -d '{ \"0\": \"800\", \"3\": \"0\", \"7\": \"0607161700\", \"11\": \"123456\", \"24\": \"0\", \"41\": \"00123456\", \"42\": \"123567890124567\" }' http://askarov.com:12346\n```\n\n## Running on Docker\n\n#### Config \n\nCreate a dummy config like so\n\n```bash\necho '{\n    \"upstreamHost\":    \"10.0.0.1\",\n    \"upstreamPort\":    5000,\n    \"listenPort\":      2014,\n    \"vv\":              true,\n    \"logFile\":         \"log.txt\"\n}\n' \u003e sample-config.json\n```\n\n#### Build image \n```bash\ndocker build -t socket-queue:latest .\n```\n\n#### Run it\n\n```bash\ndocker run -v `pwd`/sample-config.json:/etc/socket-queue/config.json -t socket-queue:latest -c /etc/socket-queue/config.json\n```\n\n#### Docker Compose\n\nThis will create a docker container and run it in three different configurations:\n\n1. SocketQueue Server listening on 2014\n2. SocketQueue Echo Server listening on port 5000\n3. SocketQueue Test Client emulating 10 clients\n\n```bash\ndocker-compose up\n```\n## Commercial collaboration\nFeel free to send your inquiries about commercial collaboration (such as payment systems integration, POS Android/iOS applications development and other payment solutions) to juks@juks.ru.\n\n## Reporting Bugs\nPlease report bugs in the Github issue tracker: https://github.com/juks/SocketQueue/issues\n\n## Copyright\nCopyright (c) 2015–2023 Igor Askarov (juks@juks.ru). See License file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuks%2Fiso-8583-socket-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuks%2Fiso-8583-socket-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuks%2Fiso-8583-socket-queue/lists"}