{"id":13621930,"url":"https://github.com/zemuldo/iso_8583","last_synced_at":"2025-04-06T22:10:05.736Z","repository":{"id":24435274,"uuid":"101483887","full_name":"zemuldo/iso_8583","owner":"zemuldo","description":":credit_card::moneybag: JavaScript library for iso 8583 messaging. Handles message validation \u0026 conversion between interfaces using iso 8583 standard. Contributors are welcome.","archived":false,"fork":false,"pushed_at":"2023-12-25T21:45:23.000Z","size":3910,"stargazers_count":85,"open_issues_count":10,"forks_count":48,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-27T16:03:03.550Z","etag":null,"topics":["8583","card","iso","iso8583","node","tcpmessage"],"latest_commit_sha":null,"homepage":"https://zemuldo.github.io/iso_8583/","language":"TypeScript","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/zemuldo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"ko_fi":"zemuldo","liberapay":"zemuldo"}},"created_at":"2017-08-26T12:18:25.000Z","updated_at":"2023-12-14T05:50:30.000Z","dependencies_parsed_at":"2023-02-13T19:00:45.489Z","dependency_job_id":"7d3ec13b-796a-4b78-864d-43ea5cd8e619","html_url":"https://github.com/zemuldo/iso_8583","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemuldo%2Fiso_8583","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemuldo%2Fiso_8583/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemuldo%2Fiso_8583/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemuldo%2Fiso_8583/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zemuldo","download_url":"https://codeload.github.com/zemuldo/iso_8583/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"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","card","iso","iso8583","node","tcpmessage"],"created_at":"2024-08-01T21:01:12.127Z","updated_at":"2025-04-06T22:10:05.680Z","avatar_url":"https://github.com/zemuldo.png","language":"TypeScript","funding_links":["https://ko-fi.com/zemuldo","https://liberapay.com/zemuldo"],"categories":["TypeScript"],"sub_categories":[],"readme":"# ISO_8583\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/zemuldo/iso_8583.svg)](https://greenkeeper.io/)~![Travis CI build badge](https://travis-ci.org/zemuldo/iso_8583.svg?branch=main)~[![Known Vulnerabilities](https://snyk.io/test/github/zemuldo/iso_8583/badge.svg?targetFile=package.json)](https://snyk.io/test/github/zemuldo/iso_8583?targetFile=package.json)\n\nISO_8583 is a \u003cspan style=\"color:green; font-size:18px\"\u003eCustomizable ISO 8583 Library for JavaScript and NodeJS\u003c/span\u003e that does message conversion between a system and an interface that exchange [ISO 8583 Financial transaction card originated messages](https://en.wikipedia.org/wiki/ISO_8583).\n\n## Install from npm using\n\n```shell\n\nnpm install --save iso_8583\n```\n\n### OR\n\n```shell\nyarn add iso_8583\n```\n\n## Basic Usage: Bitmap Messaging\n\nSee the a sample usage example see [this example](https://github.com/zemuldo/iso_8583/tree/main/example)\n\n```javascript\nconst iso8583 = require('iso_8583');\nlet data = {\n    0: \"0100\",\n    2: \"4761739001010119\",\n    3: \"000000\",\n    4: \"000000005000\",\n    7: \"0911131411\",\n    12: \"131411\",\n    13: \"0911\",\n    14: \"2212\",\n    18: \"4111\",\n    22: \"051\",\n    23: \"001\",\n    25: \"00\",\n    26: \"12\",\n    32: \"423935\",\n    33: \"111111111\",\n    35: \"4761739001010119D22122011758928889\",\n    41: \"12345678\",\n    42: \"MOTITILL_000001\",\n    43: \"My Termianl Business                    \",\n    49: \"404\",\n    52: \"7434F67813BAE545\",\n    56: \"1510\",\n    123: \"91010151134C101\",\n    127: \"000000800000000001927E1E5F7C0000000000000000500000000000000014A00000000310105C000128FF0061F379D43D5AEEBC8002800000000000000001E0302031F000203001406010A03A09000008CE0D0C840421028004880040417091180000014760BAC24959\"\n};\n\nlet customFormats = {\n    '3': {\n      ContentType: 'n',\n      Label: 'Processing code',\n      LenType: 'fixed',\n      MaxLen: 9\n    }\n  };\n\nlet isopack = new iso8583(data,customFormats);\n```\n\nThe object initialized has the following methods:\n\n#####  To validate the iso message\n\n```javascript\nisopack.validateMessage();  // returns true for valid message or error\n\n```\n\n\n#####  To get the mti as a string:\n```javascript\nisopack.getMti(); // returns a 4 byte buffer containing the mti\n\n```\n\n#####  To get the bitmaps in binary:\n\n```javascript\nisopack.getBmpsBinary(); // returns a string '1111001000111..' or an error object with error prop\n\n```\n\n#####  To get the bitmap active fields:\n\n```javascript\nisopack.getBitMapFields(); \n// returns the array of enabled fields in bitmap, excluding MTI and bitmap fields\n// e.g. [2, 3, 4, 7, 12, 13, 14, 18, 22, 23, 25, 26, 32, 33, 35, 41, 42, 43, 49, 52, 56, 123, 127]\n\n```\n\n\n#####  To get the bitmaps in hex for fields 0-127, fields 127 extensions and fields 127.25 extensions\n\n```javascript\nisopack.getBitMapHex();             // returns 'f23c46c1a8e091000000000000000022'\nisopack.getBitMapHex_127_ext();     // returns '8000008000000000'\nisopack.getBitMapHex_127_ext_25();  // returns 'fe1e5f7c00000000'\n\n// in case of error, the error object returned with error prop\n```\n\n#####  To get a raw message:\n\n```javascript\nlet bufferMessage = isopack.getRawMessage(); \n// returns a buffer containing the message (without 2-byte length field) or an error object\n\u003cBuffer 30 31 30 30 f2 3c 46 c0 20 e8 80 00 00 00 00 00 00 00 00 20 30 37 35 34 ...\n\n```\n\n#####  To get a buffer tcp message to send to the ISO 8583 Interface:\n\n```javascript\nlet bufferMessage = isopack.getBufferMessage(); \n// returns a buffer containing the message with 2 additional bytes indicating the length \n// or an error object\n\u003cBuffer 01 11 30 31 30 30 f2 3c 46 c0 20 e8 80 00 00 00 00 00 00 00 00 20 30 37 35 34 ...\n\n```\n\n##### To get the field description:\n```javascript\nconst iso8583 = require('iso_8583');\niso8583.getFieldDescription(24);\n// The object with field descriptions to be returned:\n// {24: 'Network International identifier (NII)'}\n```\n\n### To get the several fields descriptions:\n```javascript\nconst iso8583 = require('iso_8583');\niso8583.getFieldDescription([24, 37, 39]);\n// The object with field descriptions to be returned:\n// {\n//    24: 'Network International identifier (NII)'},\n//    37: 'Retrieval reference number', \n//    39: 'Response code'\n// }\n```\n\n\nTo unpack a message from the interface, that usually comes in a tcp stream/buffer just parse the incoming buffer or string to the method\n\n```javascript\nlet incoming = new isopack().getIsoJSON(incoming);\n// returns parsed json object:\nlet testData = {\n    \"0\": \"0100\",\n    \"2\": \"5413330\",\n    \"3\": \"000000\",\n    \"4\": \"000000002000\",\n    \"7\": \"0210160607\",\n    \"11\": \"148893\",\n    \"12\": \"160607\",\n    \"13\": \"0210\",\n    \"14\": \"2512\",\n    \"18\": \"4111\",\n    \"22\": \"141\",\n    \"23\": \"003\",\n    \"25\": \"00\",\n    \"26\": \"12\",\n    \"35\": \"5413330089020011D2512601079360805F\",\n    \"41\": \"31327676\",\n    \"42\": \"4D4F424954494C4\",\n    \"43\": \"My Termianl Business                    \",\n    \"49\": \"404\",\n    \"45\": \"0303030204E4149524F4249204B452dataString04B45\",\n    \"123\": \"09010001000105010103040C010001\"\n};\n\n```\n\n## Basic Usage: XML Messaging\n\n### To get xml from a json\n\nInitialize the iso object with the json as argument\n\n```javascript\nlet isoPack = new isoPack(testData);\nisoPack.getXMLString();     // returns a string of iso 8583 xml string\n```\n\n\nTo get json form the xml string\n```javascript\nlet isoPack = new isoPack();    // Initialize with no argument\n```\n\nParse the string to the method to get the iso json\n\n```javascript\nlet xmlData = '\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\\n' +\n    '\u003cIso8583PostXml\u003e\\n' +\n    '\u003cMsgType\u003e0200\u003c/MsgType\u003e\\n' +\n    '\u003cFields\u003e\\n' +\n    '\u003cField_002\u003e4839123456709012\u003c/Field_002\u003e\\n' +\n    '\u003cField_003\u003e000000\u003c/Field_003\u003e\\n' +\n    '\u003cField_004\u003e000000001500\u003c/Field_004\u003e\\n' +\n    '\u003cField_007\u003e0604074705\u003c/Field_007\u003e\\n' +\n    '\u003cField_011\u003e804058\u003c/Field_011\u003e\\n' +\n    '\u003cField_012\u003e074808\u003c/Field_012\u003e\\n' +\n    '\u003cField_013\u003e0604\u003c/Field_013\u003e\\n' +\n    '\u003cField_014\u003e0812\u003c/Field_014\u003e\\n' +\n    '\u003cField_015\u003e0905\u003c/Field_015\u003e\\n' +\n    '\u003cField_022\u003e901\u003c/Field_022\u003e\\n' +\n    '\u003cField_025\u003e02\u003c/Field_025\u003e\\n' +\n    '\u003cField_026\u003e05\u003c/Field_026\u003e\\n' +\n    '\u003cField_028\u003e000000500\u003c/Field_028\u003e\\n' +\n    '\u003cField_030\u003e000000500\u003c/Field_030\u003e\\n' +\n    '\u003cField_032\u003e483912\u003c/Field_032\u003e\\n' +\n    '\u003cField_035\u003e4839123456709012=08125876305082011\u003c/Field_035\u003e\\n' +\n    '\u003cField_037\u003eD000A0030000\u003c/Field_037\u003e\\n' +\n    '\u003cField_040\u003e507\u003c/Field_040\u003e\\n' +\n    '\u003cField_041\u003eFOFUGUT1\u003c/Field_041\u003e\\n' +\n    '\u003cField_042\u003e191121119111112\u003c/Field_042\u003e\\n' +\n    '\u003cField_043\u003ePostilion Cafeteria Rondebosch ZA\u003c/Field_043\u003e\\n' +\n    '\u003cField_049\u003e710\u003c/Field_049\u003e \u003cField_056\u003e1510\u003c/Field_056\u003e\\n' +\n    '\u003cField_059\u003e0000000072\u003c/Field_059\u003e\\n' +\n    '\u003cField_123\u003e211401213041013\u003c/Field_123\u003e\\n' +\n    '\u003cField_127_002\u003e0007713856\u003c/Field_127_002\u003e\\n' +\n    '\u003cField_127_009\u003e013040604040604016501100330000\u003c/Field_127_009\u003e\\n' +\n    '\u003cField_127_012\u003eMy Terminal Business\u003c/Field_127_012\u003e\\n' +\n    '\u003cField_127_020\u003e20100604\u003c/Field_127_020\u003e\\n' +\n    '\u003c/Fields\u003e\\n' +\n    '\u003c/Iso8583PostXml\u003e';\n\nisoPack.getJsonFromXml(xmlData); // returns a json object or an error object\n```\n\n## Usage: MTI converting\n\n### Changing current mti type\n\nInitialize the iso object with the json as argument\n\n```javascript\n  let data = {\n    0: '0400',\n    2: '4761739001010119',\n    3: '000000',\n    4: '000000005000',\n    7: '0911131411'\n  };\n\n  let isopack = new isoPack(data);\n  isoPack.toRetransmit()\n  isoPack.getMti(); // returns '0401'\n  \n  isopack = new isoPack(data);\n  isoPack.toResponse(); \n  isoPack.getMti(); // returns '0410'\n  \n  isopack = new isoPack(data);\n  isoPack.toAdvice(); \n  isoPack.getMti(); // returns '0420'\n  \n```\n\nThere are other cool stuff like ```isoPack.attachTimeStamp()``` which adds times stamps to field 7,12,13, plus more\nWhen working with xml, first change the xml to json then validate.\n\n## Configuration and Customization\n\n### Custom ISO 8583 Formats.\n\nThis library Supports custom ISO 8583 Formats, versions 1993 and 2003. This means you can decide what data types are allowed on each field, the length properties of the field and its description.\nCustom ISO 8583 formats must be passed in the format below.\n\n```javascript\n{\n      'FIELD_NAME': {\n        ContentType: 'Types accepted',\n        Label: 'Description of the field',\n        LenType: 'Length type can bee fixed or lvar ...',\n        MaxLen: Maximum length (number)\n      }\n    }\n```\n\nHere is an example of custom format for field 3. You can refer to formats in the docs to see the default formats.\n\n```javascript\n\nlet customFormats = {\n    '3': {\n      ContentType: 'n',\n      Label: 'Processing code',\n      LenType: 'fixed',\n      MaxLen: 9\n    }\n  };\n\n```\n\n### Required fields\n\nYou can also set required field for message types as you desire.\nTo use required fields you need to create a json config file and add to the class when creating a new message class, thats two ways works:\n\n```javascript\nlet isopack = new iso8583(iso);\nisopack.requiredFieldsSchema = './config/required-fields.json';\n```\n\n```javascript\nconst required_fields = './config/required-fields.json';\nlet isopack = new iso8583(iso, customFormats, required_fields);\n```\n\nAnd at the config file you can organize by process code and by messages codes, like this:\n\n```json\n[\n  {\n    \"processing_code\": \"000000\",\n    \"required_fields\": [0, 2, 4]\n  },\n  {\n    \"processing_code\": \"999999\",\n    \"required_fields\":[\n      {\n        \"0100\": [3, 7],\n        \"0500\": [3, 7, 11]\n      }\n    ]\n  }\n]\n```\n\n### Message Packaging and Un-packaging\n\nThis library uses a default mode of message encoding and packaging. If you are using a third party message source or a third party packaging source, you have to pre-format your data to meet the default encoding or configure things for yourself. See configuration for more info.\n\n### Unpacking\n\nThis only applies when you are receiving messages from others sources that don't encode as per this library like JPos.\nDefault unpack conditions:\n\n`2-byte leng header in hex` + `4-byte MTI encoded in utf8` + `16-byte Bitmap encoded in hex`\n\nIf the message you are receiving is in a different state, the passing config to `getIsoJSON` like below.\n\n### Packing\n\nMessages are packaged as:\n\n- 2 byte length indicator + 4 byte message type + 16 byte bitmap(primary + secondary bitmap) + message field data.\n- Each field with variable length data is preceded with the actual length of the data in that field.\n\n\n######  \u003cspan style=\"color:blue\"\u003eField 127 and 127.25\u003c/span\u003e\n\n\u003eThe library extends fields 127 and fields 127.25 to their sub fields.    \n\u003eIf you are handling a json with field 127 or 127.25 as one string, the bitmap must be 16 character string then a 4 digit number indicating the length\n\u003eIn the above case the library will expand them.    \n\u003eIf they are already broken down to subfields, nothing changes.    \n\u003eTo invoke the package initialize with the iso8583 json or object as argument. If the json contains any fields not defined in iso8583 or has no field 0, the error is returned in an object.    \n\u003eIf you want to handle xml iso 8583 messages, the usage is described down there. \n\n## \u003cspan style=\"color:green\"\u003eThanks\u003c/span\u003e , \u003cspan style=\"color:blue\"\u003eHave\u003c/span\u003e \u003cspan style=\"color:orange\"\u003eFun\u003c/span\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzemuldo%2Fiso_8583","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzemuldo%2Fiso_8583","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzemuldo%2Fiso_8583/lists"}