The project is here to demonstrate how our SDK for Target2 (RTGS) Message Translator works. For our demonstration we are going to use the demo SDK which can translate MT to CBPR+ messages.
This documentation describes how to incorporate the Target2 (RTGS) Translator Library into your project. The SDK is written in Java.
By following this guide you will be able to translate MT(ISO 15022) messages to Target2 (RTGS) messages
and vice versa according to Target2 (RTGS) guidelines.
It's a simple maven project, you can download it and run it, with Java 1.8 or above.
Incorporate the SDK jar
into your project by the regular IDE means.
This process will vary depending upon your specific IDE and you should consult your documentation on how to deploy a bean.
For example in Intellij all that needs to be done is to import the jar files into a project. Alternatively, you can import it as a Maven or Gradle dependency.
Define repository in the repositories section
<repository>
<id>paymentcomponents</id>
<url>https://nexus.paymentcomponents.com/repository/public</url>
</repository>Import the SDK
<dependency>
<groupId>gr.datamation</groupId>
<artifactId>translator-rtgs</artifactId>
<version>4.3.0</version>
<classifier>demo</classifier>
</dependency>Import additional dependencies if not included in your project
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<version>2.5.11</version>
<scope>compile</scope>
<type>pom</type>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>org.glassfish.jaxb</groupId>
<artifactId>jaxb-runtime</artifactId>
<version>2.3.1</version>
</dependency>Define repository in the repositories section
repositories {
maven {
url "https://nexus.paymentcomponents.com/repository/public"
}
}Import the SDK
implementation 'gr.datamation:translator-rtgs:4.3.0:demo@jar'Import additional dependencies if not included in your project
implementation group: 'org.codehaus.groovy', name: 'groovy-all', version: '2.5.11', ext: 'pom'
implementation group: 'javax.xml.bind', name: 'jaxb-api', version: '2.3.1'
implementation group: 'org.glassfish.jaxb', name: 'jaxb-runtime', version: '2.3.1'| MT message | MX message | Translator Class | Multiple MX support | Available in Demo |
|---|---|---|---|---|
| MT103 | pacs.008.001.08 | Mt103ToPacs008 | ✗ | |
| MT103+ | pacs.008.001.08 | Mt103ToPacs008 | ✗ | |
| MT103(Return) | pacs.004.001.09 | Mt103ToPacs004 | ✗ | |
| MT202 | pacs.009.001.08 | Mt202ToPacs009 | ✗ | ✓ |
| MT202COV | pacs.009.001.08 | Mt202ToPacs009 | ✗ | |
| MT202(Return) | pacs.004.001.09 | Mt202ToPacs004 | ✗ | |
| MT204 | pacs.010.001.03 | Mt204ToPacs010 | ✓ |
* Multiple MX are splitted in text by an empty line
| MT message | MX message | Translator Class | Multiple MT support | Available in Demo |
|---|---|---|---|---|
| camt.053.001.08 | MT940 | Camt053ToMt940 | ✓ | |
| camt.054.001.08 | MT900 | Camt054ToMt900 | ✗ | |
| camt.054.001.08 | MT910 | Camt054ToMt910 | ✗ | |
| pacs.004.001.09 | MT103 (Return) | Pacs004ToMt103 | ✗ | |
| pacs.004.001.09 | MT202 (Return) | Pacs004ToMt202 | ✗ | |
| pacs.008.001.08 | MT103 | Pacs008ToMt103 | ✗ | |
| pacs.009.001.08 | MT202 | Pacs009ToMt202 | ✗ | ✓ |
| pacs.009.001.08 | MT202COV | Pacs009ToMt202COV | ✗ | |
| pacs.010.001.03 | MT204 | Pacs010ToMt204 | ✗ | |
| pacs.002.001.10 | MT012 | Pacs002ToMt012 | ✗ | |
| pacs.002.001.10 | MT019 | Pacs002ToMt019 | ✗ |
You have the option to provide the MT or RTGS message and the library auto translates it to its equivalent.
Input should be in text format.
Output could be either in text format or an Object.
You need to call the following static methods of RtgsTranslator class.
In case of no error of the input message, you will get the translated message.
When MT message is used as input it is not validated.
Translated message is not validated.
public static String translateMtToMx(String mtMessage) throws InvalidMtMessageException, StopTranslationException, TranslationUnhandledException
public static CoreMessage[] translateMtToMxObject(String mtMessage) throws InvalidMtMessageException, StopTranslationException, TranslationUnhandledExceptionpublic static String translateMxToMt(String mxMessage) throws InvalidMxMessageException, StopTranslationException, TranslationUnhandledException
public static SwiftMessage[] translateMxToMtObject(String mxMessage) throws InvalidMxMessageException, StopTranslationException, TranslationUnhandledExceptionIf you do not want to use the auto-translation functionality, you can call directly the Translator you want.
In this case you need to know the exact translation mapping.
Translator classes implement the MtToTarget2Translator or Target2ToMtTranslator interface.
The translate(Object), does not validate the message.
The translate(String), validates the message only in case of MX as input.
Translated message is not validated.
MtToTarget2Translator interface provides the following methods for both text and object format translations.
String translate(String swiftMtMessageText) throws InvalidMtMessageException, StopTranslationException, TranslationUnhandledException;
CoreMessage translate(SwiftMessage swiftMtMessage) throws StopTranslationException, TranslationUnhandledException;
CoreMessage[] translateMultipleMx(SwiftMessage swiftMtMessage) throws StopTranslationException, TranslationUnhandledException;The method translateMultipleMx translates an MT message to multiple ISO20022 messages.
Target2ToMtTranslator interface provides the following methods.
String translate(String mxMessageText) throws InvalidMxMessageException, StopTranslationException, TranslationUnhandledException;
SwiftMessage translate(CoreMessage coreMessage) throws StopTranslationException, TranslationUnhandledException;
SwiftMessage[] translateMultipleMt(CoreMessage coreMessage) throws StopTranslationException, TranslationUnhandledException;The method translateMultipleMt translates an RTGS message to multiple MT messages.
You can see in table below which translations support this.
In case that a translation uses this logic, the translation in text format will return the MT messages splitted with $.
For example:
:56A:INTERBIC
-}${1:F01TESTBICAXXXX1111111111}
In order to validate the translated MX message, you can use MxMessageValidationUtils.validateMxMessage(T message),
RtgsMessageValidationUtils.autoParseAndValidateRtgsMessage(String messageText) or any other way you prefer.
When you translate a message, input message is validated (MT is excluded). For example, in a MX→MT translation, the
first step is to validate the MX message and we proceed to translation only if the message is valid.
This is the reason why this direction throws InvalidMxMessageException.
Both Exceptions contain a validationErrorList attribute which contains a description of the errors occurred.
When there is a condition in input message that obstructs the translation, a StopTranslationException is thrown which
contains a translationErrorList. The TranslationError has the structure:
- errorCode
- errorCategory
- errorDescription
When there is an exception that is not known, like NullPointerException, an TranslationUnhandledException is thrown the
actual exception is attached as the cause.
Once you have the translated message as text, you can use our other Financial Messaging Libraries (Other Resources) in order to create a Java Object and make any changes you want.
In order to create an RTGS Java Object use the below code. The object class FinancialInstitutionCreditTransfer08Rtgs may vary depending on the ISO20022 Message Type.
Other message types are available here
FinancialInstitutionCreditTransfer08Rtgs financialInstitutionCreditTransfer08Rtgs = new FinancialInstitutionCreditTransfer08Rtgs();
financialInstitutionCreditTransfer08Rtgs.parseXML(xml);In order to create an MT Java Object use the below code.
SwiftMessage swiftMessage = new SwiftMsgProcessor().ParseMsgStringToObject(translatedMessage);When you choose the Explicit Translation, you can set values that cannot be retrieved from pacs.002 before calling the translation.
For MT012:
Pacs002ToMt012 pacs002ToMt012 = new Pacs002ToMt012();
pacs002ToMt012.setTime("1037"); //Tag175
pacs002ToMt012.setMir("210610TESTBICAAXXX0945872653"); //Tag106
pacs002ToMt012.setMur("AAAA"); //Tag108
pacs002ToMt012.setSwiftAddress("TESTBICBXXXX"); //Tag102
pacs002ToMt012.setPaymentReleaseInformationSender("103723103723GR000RTGS331956001"); //Tag114
String mtMessage = pacs002ToMt012.translate(message);For MT019:
Pacs002ToMt019 pacs002ToMt019 = new Pacs002ToMt019();
pacs002ToMt019.setTime("1037"); //Tag175
pacs002ToMt019.setMir("210610TESTBICAAXXX0945872653"); //Tag106
pacs002ToMt019.setMur("AAAA"); //Tag108
pacs002ToMt019.setSwiftAddress("TESTBICBXXXX"); //Tag102
pacs002ToMt019.setMor("103723103723GR000RTGS331956001"); //Tag107
String mtMessage = pacs002ToMt019.translate(message);After translation is completed, we have a message with dummy values in for sender and receiver in Heade Blocks.
In order to set the correct values we call method RtgsMx2MtUtils.fillHeaderBlocks().
If we have the BusinessApplicationHeader, we can call it like this:
//bah is an instance of BusinessApplicationHeader01Rtgs
RtgsMx2MtUtils.fillHeaderBlocks(bah, swiftMessage, "O", "012", null, null, null);We can also call it without the header:
//bah is an instance of BusinessApplicationHeader01Rtgs
RtgsMx2MtUtils.fillHeaderBlocks(swiftMessage, "O", "012", "TESTBICZ", "TESTBICA", null, null, null, null)In this project you can see code for all the basic manipulation of an MX message, like:
- More information about our implementation of MT library can be found in our demo on PaymentComponents GitHub.
- More information about our implementation of ISO20022 library can be found in our demo on PaymentComponents GitHub.
- More information about our implementation of RTGS library can be found in our demo on PaymentComponents GitHub.