Camel Components

ISO-8583

Since Camel 4.14

This iso8583 data format supports reading and writing ISO-8583 messages (using the j8583 parser library).

ISO-8583 is a message format used for credit card transactions, banking and other commercial interaction between different systems. It has an ASCII variant and a binary one, and it is somewhat convoluted and difficult to implement.

ISO-8583 Options

The ISO-8583 dataformat supports the following options which are listed below.

Name Default Java Type Description

configFile (common)

j8583-config.xml

String

The j8583 configuration file. It is loaded from the classpath by default; use the file: or http: prefix to load it from somewhere else.

isoType (common)

String

The default ISO-Type to use.

allowAutoWiredMessageFormat (advanced)

true

Boolean

Whether to auto-discover com.solab.iso8583.MessageFactory from the registry.

Message Body

The message body at each side of the ISO-8583 data format: Marshal input and Unmarshal input are the bodies marshal and unmarshal can take, and Marshal output and Unmarshal output the body after them.

Side Body Description

Marshal input

pojo (com.solab.iso8583.IsoMessage)

A j8583 IsoMessage, such as unmarshal gives. A Map is not converted.

Marshal output

stream

The ISO-8583 message in the stream cache, or a byte array when stream caching is off: ASCII or binary, as the j8583 configuration says.

Unmarshal input

text, bytes, stream or file

An ISO-8583 message of the ISO-Type in the CamelIso8583IsoType header, or else the isoType option: unmarshal fails without either.

Unmarshal output

pojo (com.solab.iso8583.IsoMessage)

A j8583 IsoMessage: getAt(n) gives field n.

The bodies are the ones with the default options. A side that is not listed is not known, and tooling does not guess it. The carriers, the sides and the tools that use them are described in Message Body Types.

ISO-Types

These are some of the most common message types.

There is some logic to this, if you look at the message types as 2-byte hex values: The first byte states the type of operation: 02 are payments, 04 reversals, 08 tests; the second byte indicates if it’s a request or a response. And sometimes repeated requests should end in 1 instead of 0, for example reversals are 0400 the first time but 0401 the next time you send them.

ISO-Type

Description

0200

A payment or sale request

0210

A payment or sale response

0400

A reversal request (to undo a previous 0200 operation)

0410

A reversal response

0600

A query (to check the status of a previous operation, or check an account’s balance, etc)

0610

A query response

0800

An echo request (just to keep the connection alive and make sure the other side is responsive)

0810

An echo response

See more information at the j8583 docs.

Configuration

The J8583 parser can be configured using j8583-config.xml configuration file that should be located in src/main/resources so it can be loaded from the classpath.

This configuration file should contain the support ISO-8583 mappings.

The configFile option sets another configuration file. It is loaded from the classpath by default, and the prefixes classpath:, file: and http: select where to load it from, such as file:/etc/myapp/j8583-config.xml. The data format fails at startup when a configFile that is set cannot be found.

Specifying ISO-Type per message

The data format requires to know the ISO-Type of the message to understand how to parse the data. A default ISO-Type can be configured on the data format. However, you can use a custom header with id CamelIso8583IsoType on the Exchange message to override and specify another ISO-Type, such as:

  • Java

  • XML

  • YAML

from("direct:payment")
    .setHeader("CamelIso8583IsoType", constant("0200"))
    .unmarshal().iso8583()
    .to("bean:payment");
<route>
  <from uri="direct:payment"/>
  <setHeader name="CamelIso8583IsoType"><constant>0200</constant></setHeader>
  <unmarshal><iso8583/></unmarshal>
  <to uri="bean:payment"/>
</route>
- route:
    from:
      uri: direct:payment
      steps:
        - setHeader:
            name: CamelIso8583IsoType
            constant: "0200"
        - unmarshal:
            iso8583: {}
        - to:
            uri: bean:payment

Example

You can use this data format to unmarshal a ISO-8853 message such as a 0210 payment response, and then select the information from the message you need and covert this to JSon as shown below:

  • Java

  • XML

  • YAML

from("jms:queue:payment:response")
        .unmarshal().iso8583("0210")
        .transform().simple(
            """
                  {
                    "op": "${body.getAt(3).value}",
                    "amount": ${body.getAt(4).value.toPlainString},
                    "ref": "${body.getAt(37).value}",
                    "response": "${body.getAt(39).value}",
                    "terminal": "${body.getAt(41).value}",
                    "currency": "${body.getAt(49).value}"
                  }
            """)
        .to("direct:payementResponse");
<route>
  <from uri="jms:queue:payment:response"/>
  <unmarshal><iso8583 isoType="0210"/></unmarshal>
  <transform>
    <simple>{
  "op": "${body.getAt(3).value}",
  "amount": ${body.getAt(4).value.toPlainString},
  "ref": "${body.getAt(37).value}",
  "response": "${body.getAt(39).value}",
  "terminal": "${body.getAt(41).value}",
  "currency": "${body.getAt(49).value}"
}</simple>
  </transform>
  <to uri="direct:payementResponse"/>
</route>
- route:
    from:
      uri: jms:queue:payment:response
      steps:
        - unmarshal:
            iso8583:
              isoType: "0210"
        - transform:
            simple: |
              {
                "op": "${body.getAt(3).value}",
                "amount": ${body.getAt(4).value.toPlainString},
                "ref": "${body.getAt(37).value}",
                "response": "${body.getAt(39).value}",
                "terminal": "${body.getAt(41).value}",
                "currency": "${body.getAt(49).value}"
              }
        - to:
            uri: direct:payementResponse

Instead of simple language you can also use Groovy which has a special support in J8583 library:

Java-only: using Groovy language for ISO-8583 field extraction
from("jms:queue:payment:response")
        .unmarshal().iso8583("0210")
        .transform().groovy(
            """
              [
                "op": body[3].value,
                "amount": body[4].value,
                "ref": body[37].value,
                "response": body[39].value,
                "terminal": body[41].value,
                "currency": body[49].value
              ]
            """)
        .to("direct:payementResponse");

More Information

Find more information see the J8583 project and the J8583 source code.

Dependencies

To use ISO-8583 in your camel routes, you need to add the dependency on camel-iso8583 which implements this data format.

If you use maven, you could add the following to your pom.xml, substituting the version number for the latest and greatest release.

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-iso8583</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>