Skip to content

MT-JSON Conversion

Back and forth conversion between MT messages and JSON

Different JSON structures are created depending on the model object where the toJson is invoked.

SwiftMessage JSON

When SwiftMessage#toJson() in the backbone model is used, the generated JSON contains a generic structure with plain name/value tuples for the text block as in the example below.

{ "version" : 1, "timestamp" : '2017-06-05 04:32 -0300', "data" : {
    "block1" : {
        "applicationId" : "F",
        "serviceId" : "01",
        "logicalTerminal" : "BICFOOYYAXXX",
        "sessionNumber" : "8683",
        "sequenceNumber" : "497519"
    } ,
    "block2" :  {
        "messageType" : "103",
        "senderInputTime" : "1535",
        "MIRDate" : "051028",
        "MIRLogicalTerminal" : "ESPBESMMAXXX",
        "MIRSessionNumber" : "5423",
        "MIRSequenceNumber" : "752247",
        "receiverOutputDate" : "051028",
        "receiverOutputTime" : "1535",
        "messagePriority" : "N"
    } ,
    "block4" : [
            { "20" : "0061350113089908" },
            { "13C" : "/RNCTIME/1534+0000" },
            (...)
            { "72" : "/BNF/TRANSF. BCO. FOO" }  
        ]
    }
}

AbstractMT JSON

If the message is parsed into the AbstractMT using AbstractMT#parse or by creating any of the subclasses such as the MT103, then a call to toJson() generates a similar structure, but for the text block each field is serialized into a specific structure.

{
    "type": "MT",
    "basicHeaderBlock": {
        "applicationId": "F",
        "serviceId": "01",
        "logicalTerminal": "AAAABEBBAXXX",
        "sessionNumber": "0001",
        "sequenceNumber": "000001"
    },
    "applicationHeaderBlock": {
    "receiverAddress": "BBBBBEBBXBIL",
    "messagePriority": "N",
    "messageType": "565",
    "blockType": "I",
    "direction": "I"
    },
    "userHeaderBlock": {
        "fields": [
            { "name": "108", "mUR": "495" }
        ]
    },
    "textBlock": {
        "fields": [
            { "name": "16R", "blockName": "GENL" },
            { "name": "20C", "qualifier": "CORP", "reference": "ABCD1234" },
            { "name": "20C", "qualifier": "SEME", "reference": "123456789124001" },
            { "name": "23G", "function": "NEWM" },
            { "name": "22F", "qualifier": "CAEV", "indicator": "CONV" },
            { "name": "98C", "qualifier": "PREP", "date": "20210912", "time": "123111" },
            { "name": "16R", "blockName": "LINK" },
            { "name": "22F", "qualifier": "LINK", "indicator": "INFO" },
            { "name": "13A", "qualifier": "LINK", "numberId": "564" },
            { "name": "20C", "qualifier": "RELA", "reference": "NONREF" },
            { "name": "16S", "blockName": "LINK" },
            { "name": "16S", "blockName": "GENL" },
            { "name": "16R", "blockName": "CAINST" },
            { "name": "13A", "qualifier": "CAON", "numberId": "002" },
            { "name": "22F", "qualifier": "CAOP", "indicator": "CONY" },
            { "name": "35B", "qualifier": "ISIN", "iSIN": "LU0123456789", "description": "ABCD CORP ORD SHS" },
            { "name": "36B", "qualifier": "QINS", "quantityTypeCode": "FAMT", "quantity": "50000," },
            { "name": "16S", "blockName": "CAINST" }
        ]
    }
}

NarrativeContainer fields JSON

When serializing the field into its specific structure, Field#toJson() in the backbone model is used, there is a special treatment if the field is a NarrativeContainer.

These fields support having a simple unstructured content split in lines and also a structured version with codewords.

The codewords are separated with slashes and can be used to categorize part of the narrative content.

When the structured option is used, different line formats are supported depending on the actual field. In most of the fields the only element in the structured format is the actual text. Some fields can include bank code, currency and amount, country codes or the narrative partitioned as a main narrative and a supplement.

Supported line formats are:

  • Format 1

    • Line 1: /8a/[additional information] (Code)(Narrative)
    • Lines 2-n: /8a/[additional information] (Code)(Narrative) or [//continuation of additional information] (Narrative)

  • Format 2

    • Line 1: /8c/[additional information] (Code)(Narrative)
    • Lines 2-n: /8c/[additional information] (Code)(Narrative) or [//continuation of additional information] (Narrative)

  • Format 3

    • Line 1: /8c/[3!a13d][additional information] (Code)(Currency)(Amount)(Narrative)
    • Lines 2-6: /8c/[3!a13d][additional information] (Code)(Currency)(Amount)(Narrative) or [//continuation of additional information] (Narrative)

  • Format 4

    • Line 1: /8c/[additional information] (Code)(Narrative)

    • Lines 2-3: [//continuation of additional information] (Narrative)

    • Variant for cat 1 with country

    • Line 1: /8c/2!a[//additional information] (Code)(Country)(Narrative)
    • Lines 2-3: [//continuation of additional information] (Narrative)

  • Format 5

    • Line 1: /2n/[supplement 1][/supplement2] (Query Number)(Narrative 1)(Narrative 2)
    • Lines 2-6: /2n/[supplement 1][/supplement2] or [//continuation of supplementary information]

  • Format 6

    • Line 1: /6c/[additional information] (Code)(Narrative)
    • Lines 2-100: /6c/[additional information] (Code)(Narrative) or [continuation of additional information] (Narrative) (cannot start with slash)

  • Format 7

    • Code between slashes at the beginning of a line

  • Format 8

    • Free format codes in slashes, not necessary on new lines

Thus the JSON conversion, will include both the plain narrative lines, and also the result of serializing into JSON the same content parsed into Narrative model, returning for example this JSON content:

{
  "name":"71B",
  "narrative":"/WITX/CAPITAL GAINS TAX RELATING TO\n//THE PERIOD 1999-01-01 2022-10-30\n//REF 009524780123\n//BANCA DEL TEST\n//(REF. ART. 6 DL 461/97)",
  "structured":[
    {
      "narrativeFragments":[
        "CAPITAL GAINS TAX RELATING TO",
        "THE PERIOD 1999-01-01 2022-10-30",
        "REF 009524780123",
        "BANCA DEL TEST",
        "(REF. ART. 6 DL 461/97)"
      ],
      "narrativeSupplementFragments":[],
      "codeword":"WITX"
    }
  ],
  "unstructuredFragments":[]
}

As for the reverse conversion, the from JSON method can consume either the plain narrative line elements or the structured narrative elements.

Meaning the reverse can consume also a JSON with this structure:

{
  "name":"71B",
  "narrative":"/WITX/CAPITAL GAINS TAX RELATING TO\n//THE PERIOD 1999-01-01 2022-10-30\n//REF 009524780123\n//BANCA DEL TEST\n//(REF. ART. 6 DL 461/97)",
}

And also this other version, producing the same Field71B instance:

{
  "name":"71B",
  "structured":[
    {
      "narrativeFragments":[
        "CAPITAL GAINS TAX RELATING TO",
        "THE PERIOD 1999-01-01 2022-10-30",
        "REF 009524780123",
        "BANCA DEL TEST",
        "(REF. ART. 6 DL 461/97)"
      ],
      "narrativeSupplementFragments":[],
      "codeword":"WITX"
    }
  ],
  "unstructuredFragments":[]
}

Finally for backward compatibility, the JSON unmarshaller can also consume a JSON with the plain narrative lines split into individual elements such as:

{
  "name":"71B",
  "narrative":"/WITX/CAPITAL GAINS TAX RELATING TO",
  "narrative2":"//THE PERIOD 1999-01-01 2022-10-30",
  "narrative3":"//REF 009524780123",
  "narrative4":"//BANCA DEL TEST",
  "narrative":"//(REF. ART. 6 DL 461/97)"
}

MtSwiftMessage JSON

Finally, there also exists yet another JSON structure if serialization is done using the persistence model MtSwiftMessage.

Given the following message content:

    {1:F01AAAAUSC0ADDD0344000050}{2:I103BBBBUSC0XFFFN}{4:
    :20:TBEXO200909031
    :23B:CRED
    :32A:090903USD23453,
    :50K:/01111001759234567890
    JOE DOE
    R00000V0574734
    :53B:/00010013800002001234
    MI BANCO
    :59:/00013500510020179998
    FOO CORP
    R00000V000034534
    :71A:OUR
    :72:/TIPO/422
    -}{5:{PDE:FOO}}

If the message is parsed into an MtSwiftMessage model structure, and some status info and message notes are added, the JSON representation would be like this:

{
  "pde": "FOO",
  "uuid": "IBBBBUSC0FFF103TBEXO200909031",
  "identifier": "fin.103",
  "sender": "AAAAUSC0DDD",
  "receiver": "BBBBUSC0FFF",
  "message": "{1:F01AAAAUSC0ADDD0344000050}{2:I103BBBBUSC0XFFFN}{4:\n:20:TBEXO200909031\n:23B:CRED\n:32A:090903USD23453,\n:50K:/01111001759234567890\nJOE DOE\nR00000V0574734\n:53B:/00010013800002001234\nMI BANCO\n:59:/00013500510020179998\nFOO CORP\nR00000V000034534\n:71A:OUR\n:72:/TIPO/422\n-}{5:{PDE:FOO}}",
  "direction": "outgoing",
  "checksum": "5c15a3803c4d91d7241534b01a9cf624",
  "checksumBody": "d4e96cd0c1684cfc218089875d64187b",
  "lastModified": {
    "year": 2022,
    "month": 10,
    "dayOfMonth": 17,
    "hourOfDay": 14,
    "minute": 36,
    "second": 28
  },
  "creationDate": {
    "year": 2022,
    "month": 10,
    "dayOfMonth": 17,
    "hourOfDay": 14,
    "minute": 36,
    "second": 27
  },
  "statusTrail": [
    {
      "name": "name",
      "comments": "comments",
      "creationDate": {
        "year": 2022,
        "month": 10,
        "dayOfMonth": 17,
        "hourOfDay": 14,
        "minute": 36,
        "second": 28
      },
      "creationUser": "creationUser",
      "data": "data"
    }
  ],
  "notes": [
    {
      "creationDate": {
        "year": 2022,
        "month": 10,
        "dayOfMonth": 17,
        "hourOfDay": 14,
        "minute": 36,
        "second": 28
      },
      "creationUser": "creationUser",
      "text": "text"
    }
  ],
  "properties": {

  },
  "fileFormat": "FIN",
  "reference": "TBEXO200909031",
  "currency": "USD",
  "amount": 23453,
  "revisions": [

  ],
  "valueDate": {
    "year": 2009,
    "month": 8,
    "dayOfMonth": 3,
    "hourOfDay": 0,
    "minute": 0,
    "second": 0
  }
}