ISO-8583

As described on Wikipedia:

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.

ISO 8583 defines a message format and a communication flow so that different systems can exchange these transaction requests and responses. The vast majority of transactions made when a customer uses a card to make a payment in a store (EFTPOS) use ISO 8583 at some point in the communication chain, as do transactions made at ATMs. In particular, the MasterCard, Visa and Verve networks base their authorization communications on the ISO 8583 standard, as do many other institutions and networks.

Port Mapping

To mock ISO-8583 messages, it is necessary to tell Copycat how to interpret the received message. This is made by creating a new PortMapping using the following endpoint:

Path: /iso8583-connector/admin/ports
Method: Post
Body example:

{
    "port": 8991,
    "resourceName": "ISO-8583-port-8991",
    "timeout": 60000,
    "status": "INACTIVE",
    "mappingProperties":{
        "headerLength": 10,
        "secondaryBitmapMandatory": false,
        "tertiaryBitmapMandatory": false,
        "mtiEncodingType": "BCD",
        "headerEncodingType": "BCD",
        "bitmapEncodingType": "HEXA",
        "bitmapEncoded": true
    },
    "mapping": [{ "mti": "0100", "headers": [ {"name": "type", "length": "2"}, {"name": "destination", "length": "4"}, {"name": "origin", "length": "4"} ], "fields": [ { "id": "03", "name": "processingCode", "length": "6", "type": "NUMERIC"}, { "id": "04", "name": "amount", "length": "12", "type": "NUMERIC"}, { "id": "11", "name": "stan", "length": "6", "type": "NUMERIC"}, { "id": "48", "name": "additionalData", "length": "999", "type": "LLLVAR", "tags": [ { "id": "02", "name": "a1", "length": "8" , "type": "LLLVAR"}, { "id": "43", "name": "a2", "length": "14", "type": "LLLVAR"} ]} ] }, { "mti": "0110", "fields": [ { "id": "03", "name": "processingCode", "length": "6", "type": "NUMERIC"}, { "id": "11", "name": "stan", "length": "6", "type": "NUMERIC"}, { "id": "39", "name": "responseCode", "length": "2", "type": "ALPHA" } ] }]
}

The mapping field present on the body describes all supported message types. Let's take a closer look at this field with an explained example:

[
  {
    "mti": "0100",
    "headers": [
        {"name": "type",        "length": "2"},
        {"name": "destination", "length": "4"},
        {"name": "origin",      "length": "4"}
    ],
    "fields": [
      { "id": "03", "name": "processingCode",       "length": "6",   "type": "NUMERIC"},
      { "id": "04", "name": "amount",               "length": "12",  "type": "NUMERIC"},
      { "id": "11", "name": "stan",                 "length": "6",   "type": "NUMERIC"},
      { "id": "48", "name": "additionalData",       "length": "999", "type": "LLLVAR", "tags": [
          { "id": "02", "name": "a1", "length": "8" , "type": "LLLVAR"},
          { "id": "43", "name": "a2", "length": "14", "type": "LLLVAR"}
      ]}
    ]
  },
  {
    "mti": "0110",
    "fields": [
      { "id": "03", "name": "processingCode", "length": "6",  "type": "NUMERIC"},
      { "id": "11", "name": "stan",           "length": "6",  "type": "NUMERIC"},
      { "id": "39", "name": "responseCode",   "length": "2",  "type": "ALPHA"  }
    ]
  }
]

The JSON is composed by an array of message types that are formed by an MTI (Message Type Indicator) and a list of fields. The following table describes the message type object:

Name	Mandatory	Default	Description
mti	true	n/a	An ISO defined field that indicates the purpose of the message
fields	true	n/a	The fields array contains a list of ISO defined data elements that are expected on this message
fields.id	true	n/a	Represents the data field identification number
fields.name	false	The value of `id` field	An optional name to describe the field. This will be used on Scenarios to match the received body. If this is not present, the `num` field will be used instead
fields.length	true	n/a	The expected length of the field. For fields with variable length, this represents the maximum length
fields.type	true	n/a	Must be one of NUMERIC, ALPHA, LLVAR, LLLVAR. Support for more types will be added latter
fields.encoding	false	BCD	Must be one of BCD, BCD_EVEN_LENGTH, BCD_DOUBLE_LENGTH, HEXA, HEXA_EBCDIC.
fields.charset	false	UTF-8 (Cp1047 if HEXA_EBCDIC)	The field charset, used to encode/decode string.
fields.encodedLength	false	false	Should be set to `true` if the field length is encoded, otherwise Copycat will not be able to read the field's length
fields.encodedTagName	false	false	Should be set to `true` if the tag name is encoded, otherwise Copycat will not be able to read the tag's name
fields.tags	false	empty array	A field may contain an array of tags, and a tag can contain the same attributes described previously for fields

Port Mapping Status

A Port Mapping can be ACTIVE or INNACTIVE meaning Copycat will only listen to connections for ports that have an ACTIVE Port Mapping.

The status can be changed using the following endpoint:

Path: /iso8583-connector/admin/ports/{{port_number}}/status/{{status}}
Method: PUT

ISO-8583 Scenarios

This section describes the fields that are exclusive for ISO-8583. For all other fields, please refer to Scenarios section.

Name	Mandatory	Description
key.mti	true	The mti works as an unique identifier for the Scenario group. All Scenarios of the given MTI must be grouped on the same JSON
request.connectionId	true	This field is provided by Copycat, it is an unique identification of the connection from which Copycat received the message
request.originIp	true	This field is provided by Copycat, it contains the IP of the message sender
response.mti	true	The message type that will be returned for the given scenario
defaultResponse.mti	true	Works exactly the same way as `response.mti`
fallbackResponse.mti	false	Works exactly the same way as `response.mti`. The fallbackResponse field is not mandatory, but if it is present, then this field is mandatory
callback.typeProperties.mti	true	The message type that will be used on the message that will be sent as callback
callback.typeProperties.portMapping	true	The port number of the portMapping that will be used to send the callback. This is the mapping that will be used to transform the JSON payload into an ISO8583 message. Either this field or `callback.typeProperties.ip` must be provided
callback.typeProperties.connectionId	false	The connection that will be used to send the callback. This field can receive de value of `request.connectionId`. Either this field or `callback.typeProperties.ip` must be provided
callback.typeProperties.ip	false	The IP that will be used to send the callback, if there is no connection active for this IP, Copycat will attempt to open a new connection. This field can receive the value of `request.originIp`. Either this field or `callback.typeProperties.connectionId` must be provided