SWIFT SDK for Java Configuration Management Guide
SWIFT SDK for Java
Configuration Management Guide
This guide is a description of SDK configuration parameters with examples.
10 May 2022
Page 1
SWIFT SDK for Java Configuration Management Guide
Table of Contents 1 SWIFT SDK for Java Configuration Management Guide .......................................................... 3 2 SWIFT SDK Configuration ...................................................................................................... 4 2.1 Environment Variables ............................................................................................................ 4 2.2 SWIFT SDK Configuration Settings .......................................................................................... 4 2.3 hosts ........................................................................................................................................ 4 2.3.1 api_gateway .................................................................................................................... 4 2.3.2 gpi_connector ................................................................................................................. 5 2.4 services.................................................................................................................................... 7 2.5 security_footprints.................................................................................................................. 7 2.5.1 common .......................................................................................................................... 7 2.5.2 software_certificate ........................................................................................................ 7 2.5.3 sags.................................................................................................................................. 7 2.5.4 lau.................................................................................................................................... 8 2.5.5 basic ................................................................................................................................ 8 3 SWIFT SDK business properties configuration ........................................................................ 9 3.1 properties.tracker ................................................................................................................... 9 3.2 properties.preval................................................................................................................... 10 3.3 properties.g4c ....................................................................................................................... 11 3.4 properties.mtapp .................................................................................................................. 11 3.5 properties.swiftref ................................................................................................................ 11 3.6 properties.sads...................................................................................................................... 12 3.7 properties.kyc ....................................................................................................................... 13 3.8 properties.compliance .......................................................................................................... 13 3.9 properties.banking ................................................................................................................ 13 3.10 properties.gcase.................................................................................................................... 14 4 SDK logging configuration ................................................................................................... 15 5 API URLs ............................................................................................................................. 16 6 Configuration File Encryption (YAML file) ............................................................................ 17 7 Sample SWIFT SDK Connectivity YAML Configuration File .................................................... 19 8 Sample SWIFT SDK Business Properties YAML Configuration File.......................................... 21 9 Sample code for updating payment status on behalf of other financial institutions .............. 24 Legal Notices ............................................................................................................................. 25
Page 2
SWIFT SDK for Java Configuration Management Guide
1 SWIFT SDK for Java Configuration Management Guide The SWIFT SDK for Java provides a Java API for SWIFT API Services. Using the SDK, you can easily build Java applications that work with SWIFT API services like gpi Tracker, Pre-validation, g4C and more. This document provides details on how to set up SWIFT SDK configuration data and use the SDK to do SWIFT API services. The document is applicable for SDK 1.0.9 and above.
Note: the use of SWIFT’s SDK products (including but not limited to SWIFT Business SDK and SWIFT Security SDK) are subject to the terms and conditions contained in their applicable licence. Such applicable licences are contained in a “licence file.” Your use of the SDK products is considered your acceptance of the applicable licence terms.
The following picture depicts the connectivity topology when using SDK for doing SWIFT APIs.
Page 3
SWIFT SDK for Java Configuration Management Guide
2 SWIFT SDK Configuration
2.1 Environment Variables The Java Web Token (JWT) used to protect the API call between the SDK and its correspondents is protected with a JWT. In the construction and deserialising of the token, the Absolute Path (abs_path) is present in the claims. Several misinterpretations are possible with different versions of the SDK. This can result in an error such as “JWS validation failed. Absolute paths from JWS and http request mismatch.” To disable abs_path verification in the SDK, set the environment variable ENABLE_ABSPATH_VALIDATION=true. This variable must be set at the OS level, ideally as a property of the user launching the application. Setting this variable as a Java property will not work. This variable is also deprecated in versions of SDK 1.1.1 and above.
2.2 SWIFT SDK Configuration Settings SWIFT SDK for Java enables you to change the default client configuration. The configuration settings and local security footprints are prerequisites for connecting to SWIFT API Gateway and calling SWIFT API services. Update your configuration settings in the file named config-swift- sdk.yaml. A sample of this YAML file is provided with the SWIFT SDK package. This section provides information about the configuration of these settings.
Topics
• hosts
• services
• security_footprints
2.3 hosts You can set up API Gateway and gpi Connector host information under this section of the YAML document.
2.3.1 api_gateway Set up the configuration settings necessary to connect to SWIFT API Gateway
Attribute Name Description Example SWIFT API Gateway URL applicable Pilot: to the identified environment. It https://api- must be set to one of the test.swiftnet.sipn.swift.com following examples Live: host https://api.swiftnet.sipn.swift.com Alias name corresponding to the API Gateway Public certificate, which is used by the SDK in the context of establishing a one-way trust_alias SSL connection with API gateway si2kca Consumer Key (also known as the API Key), which is obtained from SWIFT Developer Portal while bTYyg9xnDh2TqN23ju consumer_key registering the Application. PTDjrByFKG6dgy Consumer Secret obtained by the consumer_secret developer from SWIFT Developer QpJv1OCxuN2cjizb
Page 4
SWIFT SDK for Java Configuration Management Guide
Portal while registering the Client
Application.
authorization_service Set up API Gateway session-related information
Attribute Name Description Example OAUTH 2.0 token resource absolute path Default value set to “oauth2/v1/token”. Do not url (short version). change it. Pilot: https://api- test.swiftnet.sipn.swift.com/oauth2/v1/token
Absolute path of OAUTH 2.0 token Live:
resource including the domain name (full https://api.swiftnet.sipn.swift.com/oauth2/v1/to
audience version). ken
OAuth token session scope. Examples:
scope=swift.apitracker
Scope must be defined as a list of /// pairs scope=swift.apitracker/FullViewer
with a “/” separating each component. scope=swift.apitracker/FullViewer
Only is mandatory. All other components swift.apitracker/Update
are optional. scope=swift.apitracker/FullViewer/swhqbebb
scope swift.apitracker/Update/swhqbedd
2.3.2 gpi_connector Set up the configuration settings for connecting to SWIFT API Gateway
Attribute Name Description Example host gpi Connector hostname and port. https://bewx2768:9000 Alias corresponding to the gpi Connector public certificate, which is used by the SDK in the context of establishing a one-way SSL trust_alias connection with gpi Connector. si2kca
microgateway SWIFT Microgateway provides an API integration product for SWIFT API Services. Using SWIFT Microgateway, you can easily build applications that work with SWIFT API services like gpi Tracker, Pre-validation, g4C and gCASE.
Attribute Name Description Example host Microgateway host name and port Localhost:9003 mgw_service Default value, do not change /swift/mgw
Page 5
SWIFT SDK for Java Configuration Management Guide
Alias name of Microgateway public
certificate used by SDK for
establishing a one-way SSL
trust_alias connection with Microgateway.
amqp Configure AMQP (Advanced Message Queuing Protocol) for inbound API flows in conjunction with SWIFT Microgateway
Attribute Name Description Example
AMQP Connection URL to SWIFT amqps://
imdg To achieve additional resilience, you can run SWIFT Microgateway in In-Memory Data Grid (IMDG).
Attribute Name Description Example hazelcast_instance_address Hazelcast Connection URL Localhost: 5701 hazelcast_request_queue Hazelcast Request Queue name Req_Imdg_Queue hazelcast_response_queue Hazelcast Response Queue name Resp_Imdg_Queue Instruct the SWIFT Microgateway to perform ISO ALL, REQUEST, RESPONSE, hazelcast_iso20022_validate 20022 validation NONE; Time-out to wait for response in hazelcast_response_timeout_millisec milliseconds 100000
Page 6
SWIFT SDK for Java Configuration Management Guide
2.4 services The services section contains the endpoint names that are forwarded to the SWIFT API Gateway to locate the requested business API. Each release of the SWIFT SDK has the most up-to-date default values. They may require changes if you wish to switch from the Test and Training pilot environment to the Live environment. You may also want to change the version of the service that you are using as new API versions become available. All changes require a restart of your API application. At this time, it may be useful to check the Developer Portal for a newer version of the SDK that may contain updated default values.
The naming convention used for the endpoint configuration:
Example: /swift-apitracker-pilot/vX
The ‘-pilot’ is needed only in the Test and Training environment. It is removed for access in Production
The ‘X’ is the solicited version of the API call and is incremental as versions are released
2.5 security_footprints Define security footprints applicable to your client application: software PKI certificate, Alliance Gateway and gpi Connector LAU attributes.
2.5.1 common Set the Java Key Store file attributes.
Attribute Name Description Example Location of the Java Key Store file. Common Java Key Store file for software certificate and Alliance Gateway SSL C:\\SWIFT\\ cert_path certificate. trustCertStorage.jks Alias name corresponding to the PKI cert_password certificate on the disk qwertyuioppoiuytrewq
2.5.2 software_certificate If you are using a software certificate, then set the software certificate attributes.
Attribute Name Description Example Alias name corresponding to the PKI C:\\SWIFT\\ cert_alias certificate in the Java Key Store trustCertStorage.jks
2.5.3 sags If you are using an HSM-based certificate, then configure the Alliance Gateway attributes.
Attribute Name Description Example hostname Alliance Gateway server hostname mawx5014
port Alliance Gateway Port 48002
Page 7
SWIFT SDK for Java Configuration Management Guide
Alliance Gateway SSL DN corresponding to CN=SWIFTAlliance Gateway
ssl_dn Web Platform configuration SAG1 Name of the Messaging Partner in the mp relaxed mode sni_relaxed_sdk Subject DN of the PKI certificate on the cn=apisdk,ou=orgname, user_dn HSM o=swhqbebb,o=swift Abcd1234Abcd1234 lau_key LAU Key shared with Alliance Gateway Abcd1234Abcd1234 Alias corresponding to the Alliance Gateway public certificate which is used by SDK in the context of establishing a one- ssl_alias way SSL connection with Alliance Gateway. sagalias
2.5.4 lau If you are using an HSM-based certificate, then set the Alliance Gateway attributes.
Attribute Name Description Example
Application ID as specified in swap-proxy.xml.
2.5.5 basic Credentials for accessing APIs using basic authentication.
Attribute Name Description Example username Username apiAdmin password Password Abcd1234
Page 8
SWIFT SDK for Java Configuration Management Guide
3 SWIFT SDK business properties configuration SWIFT SDK business properties file contains the configuration properties required to do business requests. This configuration file is named “config-swift-sdk-properties.yaml”. A sample of this file is available with SDK distribution. Please update the properties mentioned in this section with the right business values. This file does not require encryption.
3.1 properties.tracker The values set here are used while creating a Tracker Sample request. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details on each attribute shown in the following chart.
Attribute Name Description Example Universally Unique Identifier (UUID) URN Namespace. Used to construct value for uetr attribute in c1fd2272-7ffe-4bcc- uetr the payload. 97e2-3e7ae77cbb55 Used to construct value for from_update fromUpdate attribute in the payload. SWHQBEBB Used to construct value for from_get fromGet attribute in the payload. MGWAJPJT Used to construct value for case_identification attribute in the caseIdentification payload. 123. signature Used to construct value for signature fakeSignature attribute in the payload. Used to construct value for original_instruction_identification originalInstructionIdentification attribute in the payload. abc123 Time window. Used to construct value for 2018-01- fromDateTime from_date_time attribute in the payload. 01T00:00:00.0Z Time window. Used to construct value for 2019-01- toDateTime to_date_time attribute in the payload. 02T00:00:00.0Z Used to construct value for maximum_number maximumNumber attribute in the payload. 100 Used to construct value for paymentScenario payment_scenario attribute in the payload. PAYMENT_SCENARIO Used to construct value for instruction_identification attribute in instructionIdentification the payload. abc123 Used to construct value for my_institution_update attribute in the myInstitutionUpdate payload. SWHQBEBB Used to construct value for my_institution_get attribute in the myInstitutionGet payload. SWHQBEBB Used to construct value for 2018-01- fundsAvailable funds_available attribute in the payload. 01T17:00:00.0Z Used to construct value for forwarded_to_agent attribute in the forwardedToAgent payload. SWHQBEBB Used to construct value for amount attribute Amount in the payload. 980.00
Page 9
SWIFT SDK for Java Configuration Management Guide
Used to construct value for currency
currency attribute in the payload. USD
Used to construct value for charge_amount
chargeAmount attribute in the payload. 20
Used to construct value for
chargeCurrency chargec_currency attribute in the payload. USD
Used to construct value for
assignment_identification attribute in
assignmentIdentification the payload. resolvedreference123
businessService Used to construct value for 001
business_service attribute in the payload.
2019-04-
startTime Used to construct value for start_time 05T09:00:00.0Z
attribute in the payload.
Used to construct value for more attribute in
More the payload.
3.2 properties.preval The values set here are used while creating pre-val sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example Used to construct value for uetr attribute in 97ed4827-7b6f-4491- uetr the payload. a06f-b548d5a7512d Used to construct value for from_update prevalBic attribute in the payload. CITIUS33 Used to construct value for AA1234567890AFJSH identification identification attribute in the payload. ASKHASKLA Used to construct value for correlation_identification attribute correlationIdentification in the payload. ABCDEKGKJGKJGKJKJHKJLK Used to construct value for creditor_account attribute in the 12345678900112348 creditorAccount payload. 473827937932 Used to construct value for country country attribute in the payload. USA Used to construct value for post_code postCode attribute in the payload. 10001 Used to construct value for town_name townName attribute in the payload. New York Used to construct value for address_line1 addressLine1 attribute in the payload. 1234 Test Address Used to construct value for address_line2 addressLine2 attribute in the payload. Test Address2 Used to construct value for bic_FI attribute bicFI in the payload. Bank of Scotland Used to construct value for code attribute in 126983AGFAKJHF98 code the payload. 0090S7891234567
Page 10
SWIFT SDK for Java Configuration Management Guide
89086432
12345678098654321
2345678
Used to construct value for proprietary
proprietary attribute in the payload. Proprietary details Used to construct value for creditor_agent_branch_id attribute in creditorAgentBranchId the payload. London Branch Used to construct value for creditor_name creditorName attribute in the payload. Test Bank Name Used to construct value for any_bic anyBic attribute in the payload. Any BIC ID
3.3 properties.g4c The values set here are used while creating g4C sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example Used to construct value for uetr attribute in 97ed4827-7b6f-4491- Uetr the payload. a06f-b548d5a7512d Time window. Used to construct value for fromDateTime from_date_time attribute in the payload. 2018-01-01T00:00:00.0Z Time window. Used to construct value for toDateTime to_date_time attribute in the payload. 2019-01-02T00:00:00.0Z Used to construct value for maximumNumber maximum_number attribute in the payload. 100 Used to construct value for status attribute Status in the payload. ACCC Used to construct value for next attribute in Next the payload. next
3.4 properties.mtapp The values set here are used while running the multithreaded application (swift-sdk-1.0.8(.x)- perftests). Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example Used to configure the number of threads you Threads want to start. 5 This is the total number of uetrs in the uetrs Uetrs sample file. 1000 The path to the txt file containing the list of /var/app/docx/SWIFT/ uetr_file_path uetrs. uetrs4mtapp.txt
3.5 properties.swiftref The values set here are used while creating SWIFTRef sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Page 11
SWIFT SDK for Java Configuration Management Guide
Attribute Name Description Example The Bank Identifier Code associated with the Bic IBAN SWHQBEBB IBAN for which the corresponding BIC is Iban requested DE04500700100532013000 Lei The corresponding LEI for a given BIC effectiveDate A date in YYYY-MM-DD format 2019-01-01 The two-character ISO 3166-1 country code countryCode of the country that issued the National ID DE The scheme (or National ID type) under scheme which the National ID is defined BLZ bban Basic Bank Account Number 500700100532013000 sepaScheme SEPA service code SDD A three-character currency code for which currencyCode SSI data must be retrieved EUR The national ID (which includes the clearing code, routing code, sort code, bank and nationalID branch ID) for which details are requested 50070010 Code that indicates the SSI category for ssiCategory which SSI data must be retrieved COPA or WHLS
3.6 properties.sads The values set here are used while creating SWIFTRef Automatic Download Service sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example getAlliancePkg or filename Name of the file getBICDirectoryPkg fileFormat Format of the file txt, xml, abe, csv Frequency Frequency of download Daily or monthly The date of the file that you want to date download SLD_EU-CSFP, “SLD_EU- listName Identify the download list UKRS”
Page 12
SWIFT SDK for Java Configuration Management Guide
3.7 properties.kyc The values set here are used while creating KYC Service sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example bic Bank Identifier Code CITIUS33 documentid The ID generated for each document Restricts consumption query of KYC data published after a given date in the format lastPublishedSince YYYY-MM-DD 2019-12-30
3.8 properties.compliance The values set here are used while creating Compliance Analytics Service sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example Identification of the rating set used to qualify institutionRatingSet the risks linked to institutions. 1234 Identification of the rating set used to qualify countryRatingSet the risks linked to countries. 23 Currency into which an amount is to be converted in a currency conversion. Valid currency codes are registered with the ISO 4217 Maintenance Agency and consist of targetCurrency three contiguous letters. USD Specifies the day the reported data covers in format YYYY-MM-DD (ISO 8601 and RFC3339 reportingPeriod section 5.6). 2019-07-15 Specifies the selected institution’s presence exposure in the payment flow. DIRE_direct Filters messages on whether they were sent direction (outbound) or received (inbound). RECE_received Identifies the counterparty institution. Either Id id or group_id may be used, but not both. ABCDEFA2AP0 Identifies the group to which the institution belongs. Either id or group_id may be used, groupId but not both. ZYXWVUZ9NZ9
3.9 properties.banking The values set here are used while creating Banking Analytics Service sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example ["PMTS_payments", Specifies the market to which the banking "TRFN_trade_finance", marketCode data belongs. "TREA_treasury"] Specifies the month the reported data reportingPeriod covers. 2019-07
Page 13
SWIFT SDK for Java Configuration Management Guide
Limits the maximum number of results to
appear on a page, with a minimum of 25
(smaller values entered default to 25) and a
maximum of 1000 (entering a greater value
limit defaults to 1000). 1000 Specifies the item number from which to offset start returning results. 0
3.10 properties.gcase The values set here are used while creating KYC Service sample requests. Modify the default values with the applicable business values. You can refer to the OAS specification or Developer Portal for more details.
Attribute Name Description Example Universally Unique Identifier (UUID) URN Namespace. c1fd2272-7ffe- Used to construct value for uetr 4bcc-97e2- uetr attribute in the payload. 3e7ae77cbb55 Case assignment identification assignmentIdentification reference. Present only for Assignment Status STAT or FTHI, otherwise forwardedToAgent set it to 'Null' Identifies the payment case From assigner. GPICBICXXXX originator Status originator GPICBICXXXX caseIdentification Uniquely identifies a case UTAPCASE1 The start time for which results will be returned. Please note that from_date_time value cannot be older than 124 days from today. If value indicated is older than 124 days, the Tracker will default to the 2019-02- fromDate earliest permitted value. 21T10:30:23:02 Stop time window to filter this search, both values from_date_time and to_date_time are mutually inclusive. The value indicated 2019-02- toDate must be in the past. 21T12:30:23:02 Indicates the maximum number of transactions to be returned.
The maximum number handled
maximumNumber by the Tracker is 100. 100 Indicates the cursor value to get the next set of responses. The value of this field must be empty after the first request. The server may return a value to help the consumer navigate next through the rest of the pages.
Page 14
SWIFT SDK for Java Configuration Management Guide
narrative Case narrative status Case status ACSP caseAssignmentStatus Case assignment status MINE Additional information or additionalInformation narrative on the case Identifies the reason the unableToApplyReasonCode message was not applied MM35 Original Instruction originalInstructionIdentification Identification Code Payment1 Original Message Identification originalMessageNameIdentificationCode Code 103
4 SDK logging configuration SWIFT SDK populates the log file that can be used for trace and monitoring purposes. You can configure the log file according to the following properties.
Attribute Name Description Example This property sets the log level and the appender. Hierarchy of log level (highest to lowest): ALL TRACE DEBUG INFO WARN ERROR log4j.rootLogger FATAL INFO, out
Direct log messages to stdout
org.apache.log4j.
log4j.appender.stdout Log4j class for ConsoleAppender ConsoleAppender log4j.appender.stdout.Target Target for the stdout System.out org.apache.log4j. log4j.appender.stdout.layout Class name for Layout PatternLayout %d{yyyy-MM-dd log4j.appender.stdout.layout. HH:mm:ss} %-5p ConversionPattern Layout Pattern %c{1}:%L - %m%n
File appender
org.apache.log4j.
log4j.appender.out Log4j class for File Appender RollingFileAppender log4j.appender.out. org.apache.log4j. layout Class name for Layout PatternLayout %d{dd MMM yyyy} %d{ABSOLUTE} | %-5.5p log4j.appender.out.layout. | %t | %c{1} | session-sdk conversionPattern Layout Pattern | %m%n Appender output file name and log4j.appender.out.file location /log/session-sdk.log If this parameter is true, the file will be appended to. Otherwise, the file will log4j.appender.out.append be truncated. true log4j.appender.out.maxFileSize Appender maximum file size 100MB
Page 15
SWIFT SDK for Java Configuration Management Guide
log4j.appender.out.maxBackupIndex Number of maximum log files to keep 100
Sample Usage: • Update the log4j.properties files as required. • Pass the log4j.properites file with a location while starting the JVM, as highlighted in the following sample.
java -cp lib\swift-sdk-1.0.8(.x).jar;swift-sdk-1.0.8(.x)-tests.jar;lib\internal\swift-security-sdk-2.0.6.jar org.junit.runner.JUnitCore com.swift.sdk.gpitracker.v3.test.hard.StatusConfirmationTest
5 API URLs Functionality URL Pilot: https://api-test.swiftnet.sipn.swift.com/oauth2/v1/token Live: Get OAuth Token https://api.swiftnet.sipn.swift.com/oauth2/v1/token Pilot: Refresh OAuth Token https://api-test.swiftnet.sipn.swift.com/oauth2/v1/token Live: https://api.swiftnet.sipn.swift.com/oauth2/v1/token Pilot: Revoke OAuth Token https://api-test.swiftnet.sipn.swift.com/oauth2/v1/revoke Live: https://api.swiftnet.sipn.swift.com/oauth2/v1/revoke gpi API Tracker Service V2 Pilot: https://api-test.swiftnet.sipn.swift.com/swift-apitracker-pilot/v2
Live:
https://api.swiftnet.sipn.swift.com/swift-apitracker /v2
gpi API Tracker Service V3 Pilot: https://api-test.swiftnet.sipn.swift.com/swift-apitracker-pilot/v3
Live:
https://api.swiftnet.sipn.swift.com/swift-apitracker /v3
g4C Service V3 Pilot: https://api-test.swiftnet.sipn.swift.com/swift-apitracker-g4c-pilot/v3
Live:
https://api.swiftnet.sipn.swift.com/swift-apitracker-g4c/v3
gpi Pre-validation Service Pilot: https://api-test.swiftnet.sipn.swift.com/swift-preval-pilot/v1
Live:
https://api.swiftnet.sipn.swift.com/swift-preval/v1
Page 16
SWIFT SDK for Java Configuration Management Guide
Banking Analytics Live: https://api.swift.com/bi/banking-analytics/v1 Compliance Analytics Live: https://api.swift.com/bi/compliance-analytics/v1 Provider
Consumer
6 Configuration File Encryption (YAML file) • Update the configuration attributes in the config-swift-sdk.yaml file with the custom values applicable to your environment.
• From the command line, run the encryption command to encrypt the configuration YAML file.
Run the file-encryptor-decryptor-1.0.0.jar by providing the following as input parameters:
o com.swift.encoder.FileEncryptor
o absolute path of configuration file (config-swift-sdk.yaml)
o absolute path where the encrypted file util4config is stored
java -cp file-encryptor-decryptor-1.0.0.jar com.swift.encoder.FileEncryptor c:\swift\config-swift-sdk.yaml c:\swift\util4config
Upon executing the command, user is prompted to enter a 16-character password. Allowed
characters include alphanumeric characters, numbers, and special characters. Spaces are
not allowed as password characters.
• If modification of the configuration is required after encryption, then execute the decrypt
command by passing the following as input parameters:
o com.swift.encoder.FileEncryptor
o absolute path of the encrypted configuration file
o absolute path where the encrypted secrets file is stored
java -cp file-encryptor-decryptor-1.0.0.jar com.swift.encoder.FileDecryptor c:\swift\config.enc c:\swift\util4config
Sample output:
Note: After encryption, place the “config.enc” and the “config4util” files in any location on your computer. The current SWIFT SDK places the files under the “/var/app/docx/SWIFT/” folder (refer to the code on the next page). You can change this by modifying the “Constants.java” file under the package “com.swift.sdk.util” inside the “SWIFT-SDK” project (the code is placed inside the src folder in swift- sdk.-1.0.8(.x).zip).
Page 17
SWIFT SDK for Java Configuration Management Guide
Change the following properties in “Constans.java”:
public static final String ENC_CONFIG_FILEPATH = "/var/app/docx/SWIFT/config.enc";
public static final String ENC_SECRETS_FILEPATH = "/var/app/docx/SWIFT/util4config";
Page 18
SWIFT SDK for Java Configuration Management Guide
7 Sample SWIFT SDK Connectivity YAML Configuration File
SWIFT SDK Configuration Guide
configuration:
hosts:
api_gateway:
# Replace it with https://api-test.swiftnet.sipn.swift.com when using
pilot environment
host: "https://api.swiftnet.sipn.swift.com"
# API Gateway Public certificate Trust Alias for establishing 1-way
SSL with API gateway
trust_alias: "
Page 19
SWIFT SDK for Java Configuration Management Guide
# absPath of gpi Tracker API service version 2. Replace it with /swift-
apitracker-pilot/v” for Test and Training environment.
tracker_service_v2: "/swift-apitracker/v2"
# absPath of gpi Tracker API service version 3. Replace it with “/swift-
apitracker-pilot/v3” for Test and Training environment.
tracker_service_v3: "/swift-apitracker/v3"
# absPath of g4c service version 3. Replace it with “/swift-apitracker-
g4c-pilot/v3” for Test and Training environment.
g4c_service: "/swift-apitracker-g4c/v3"
# absPath of swift preval service version 1. Replace it with “/swift-
preval-pilot/v1” for Test and Training environment.
preval_service: "/swift-preval/v1"
# absPath of swiftref service version 1. Replace it with “/swiftref-api-
phase1-pilot/v1” for Test and Training environment.
swiftref_service: "/swiftref-api-phase1-pilot/v1"
# absPath of swiftref automatic download service version 1. Replace it
with “/swiftref-api-phase1-pilot/v1” for Test and Training environment.
sads_service: "/sads-api-phase1-pilot/v1"
# absPath of KYC service version 1. Replace it with “/kyc-api-
service/v1” for Test and Training environment.
kyc_service: "/kyc-api-service/v1"
# absPath of GCASE service version 1. Replace it with “/gcase-api-
service/v3” for Test and Training environment.
gcase_service: "/gcase-api-service/v3"
# absPath of gpi Tracker API service version 4. Replace it with “/swift-
apitracker-pilot/v4” for Test and Training environment.
tracker_service_v4: "/swift-apitracker-pilot/v4"
# absPath of Compliance Analytics Service version 4. Replace it with
“/swift-compliance-service-pilot/v1” for Test and Training environment.
compliance_analytics_service: "/swift-compliance-service-pilot/v1"
# absPath of Banking Analytics Service version 4. Replace it with
“/swift-banking-service-pilot/v1” for Test and Training environment.
banking_analytics_service: "/swift-banking-service-pilot/v1"
provider:
security_footprints:
common:
# Location of the java key store file. Common java key store file for
software certificate and SAG SSL certificate.
cert_path: "/var/app/docx/SWIFT/<keystorage.jks>"
# Alias name corresponding to the PKI certificate on the disk.
cert_password: "
Page 20
SWIFT SDK for Java Configuration Management Guide
user_dn: "<certificate_user_dn_1>"
# LAU Key to be used with SAG.
lau_key: "<lau_key_1>"
# Alias name of SAG public certificate which is used by SDK for
establishing a 1-way SSL connection with SAG.
ssl_alias: "
8 Sample SWIFT SDK Business Properties YAML Configuration File
SWIFT SDK business elements properties
properties:
services:
tracker:
uetr: "97ed4827-7b6f-4491-a06f-b548d5a7512d"
fromUpdate: "
Page 21
SWIFT SDK for Java Configuration Management Guide
fromDateTime: "2018-01-01T00:00:00.0Z"
toDateTime: "2019-01-02T00:00:00.0Z"
maximumNumber: "100"
paymentScenario: "PAYMENT_SCENARIO"
instructionIdentification: "abc123"
myInstitutionUpdate: "<our_update_bic>"
myInstitutionGet: "<our_get_bic>"
fundsAvailable: "2018-01-01T17:00:00.0Z"
forwardedToAgent: "<agent_bic>"
amount: "980."
currency: "USD"
chargeAmount: "20"
chargeCurrency: "USD"
assignmentIdentification: "resolvedreference123"
businessService: "001"
startTime: "2019-04-05T09:00:00.0Z"
more: ""
resolvedCaseIdentification: "123."
next: "next"
investigationExecutionStatus: "PDCR"
pendingPaymentReason: "PTNA"
paymentCancelationReason: "INDM"
from: "BANBUS33XXX"
transactionStatusCode: "ACSP"
transactionStatusReason: "G000"
return: "false"
settlementMethod: "INDA"
confirmedAmount: "20"
confirmedCurrency: "USD"
chargeBearer: "CRED"
cancellationReasonInformation: "DUPL"
indemnityAgreement: "INDM"
g4c:
uetr: "97ed4827-7b6f-4491-a06f-b548d5a7512d"
fromDateTime: "2018-01-01T00:00:00.0Z"
toDateTime: "2019-01-02T00:00:00.0Z"
maximumNumber: "100"
status: "ACCC"
next: "next"
preval:
uetr: "97ed4827-7b6f-4491-a06f-b548d5a7512d"
prevalBic: "<preval_bic>"
identification: "AA1234567890AFJSHASKHASKLA"
correlationIdentification: "ABCDEKGKJGKJGKJKJHKJLK"
creditorAccount: "12345678900112348473827937932"
country: "USA"
postCode: "10001"
townName: "New York"
addressLine1: "1234 Test Address"
addressLine2: "Test Address2"
bicFI: "<bic_FI>"
code:
"126983AGFAKJHF980090S789123456789086432123456780986543212345678" proprietary: "Something else goes here SWIFT" creditorAgentBranchId: "London Branch Maintains the SWIFT"
Page 22
SWIFT SDK for Java Configuration Management Guide
creditorName: "<creditor_bank_name>"
anyBic: "<any_bic>"
memberIdentification: "TTTAABBCM243673923"
swiftref:
bic: "9769798"
iban: "ABCD1234"
lei: "LEI1234"
effectiveDate: "effectiveDate1234"
countryCode: "countryCode1234"
scheme: "scheme1234"
bban: "bban1234"
sepaScheme: "sepaScheme1234"
currencyCode: "currencyCode1234"
nationalID: "nationalid1234"
ssiCategory: "ssiCategory1234"
sads:
filename: "getgpi_v1"
fileFormat: "XML"
frequency: "daily"
date: "20200512"
listname: "SLD_EU-CSFP"
kyc:
bic: ""
documentid: ""
lastPublishedSince: ""
gcase:
uetr: ""
assignmentIdentification: ""
forwardedToAgent: ""
from: ""
originator: ""
caseIdentification: ""
fromDate: ""
toDate: ""
maximumNumber: ""
next: ""
narative: ""
status: ""
caseAssignmentStatus: ""
additionalInformation: ""
unableToApplyReasonCode: ""
originalInstructionIdentification: ""
originalMessageNameIdentificationCode: ""
compliance:
institutionRatingSet: ""
countryRatingSet: ""
targetCurrency: ""
reportingPeriod: ""
exposure: ""
direction: ""
id: ""
groupId: ""
banking:
marketCode: ""
reportingPeriod: ""
Page 23
SWIFT SDK for Java Configuration Management Guide
limit: ""
offset: ""
mtapp:
threads: "1"
uetrs: "1000"
uetr_file_path: "/var/app/docx/SWIFT/uetrs_200k.txt"
provider:
consumer:
9 Sample code for updating payment status on behalf of
other financial institutions
public void getStatusConfirmation() throws SignatureContextException, SignatureGenerationException,
OAuthValidationException, OAuthFailResponseException, OAuthConnectionException, OAuthSessionException,
GpiException {
GpiTrackerImpl gpiTrackerImpl = new GpiTrackerImpl();
SessionImpl sessionImpl = new SessionImpl();
JsonObject configJson = GpiTrackerUtil.readConfigurationProperties(ENC_CONFIG_FILEPATH);
ConnectionInfo conInfo = GpiTrackerUtil.createConnectionInfo(configJson);
Map<String, Object> yamlPropsMap = GpiTrackerUtil.createYamlMap(YAML_PROPS_FILEPATH);
CamtA0100104 requestBody = CreateRequests.createStatusConfirmationRequestBody(yamlPropsMap);
String nrSignature = null;
OAuthTokenHolder oauthTokenInfo = sessionImpl.getAccessToken(conInfo, proxy, SAG_SLOT);
assertNotNull(oauthTokenInfo);
CamtA0100203 getStatusConfirmationResponse = gpiTrackerImpl.getStatusConfirmation(
oauthTokenInfo.getAccessToken(), GpiTrackerUtil.getBasePath(configJson),
requestBody, nrSignature, conInfo, proxy);
assertNotNull(getStatusConfirmationResponse);
assertNotNull(getStatusConfirmationResponse.getPaymentStatusResponse());
}
public static CamtA0100104 createStatusConfirmationRequestBody(Map<String,Object> yamlProps) { // *** ISO 20022 data model encapsulation *** CamtA0100104 body = new CamtA0100104(); body.setPaymentStatusRequest(new PaymentStatusRequest()); body.getPaymentStatusRequest().setBusinessService(BusinessService1Code._001); body.getPaymentStatusRequest().setFrom(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC, PROPERTIES_TRACKER_MY_INSTITUTION_UPDATE)); body.getPaymentStatusRequest().setUpdatePaymentScenario(PaymentScenario1Code.CCTR); body.getPaymentStatusRequest().setUetr(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC, PROPERTIES_TRACKER_UETR));
body.getPaymentStatusRequest().setInstructionIdentification(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC,PROPERTIES_TRACKER_INSTRUCTION_ID);
body.getPaymentStatusRequest().setPaymentStatus(new PaymentStatusType3());
body.getPaymentStatusRequest().getPaymentStatus().setOriginator(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC,
PROPERTIES_TRACKER_FROM_UPDATE)); body.getPaymentStatusRequest().getPaymentStatus().setTransactionStatus(new PaymentStatus9()); body.getPaymentStatusRequest().getPaymentStatus().getTransactionStatus().setStatus(TransactionIndividualStatus5Code.ACSP); body.getPaymentStatusRequest().getPaymentStatus().getTransactionStatus().setReason(PaymentStatusReason3Code.G003); body.getPaymentStatusRequest().getPaymentStatus().setConfirmedAmount(new ActiveOrHistoricCurrencyAndAmount()); body.getPaymentStatusRequest().getPaymentStatus().getConfirmedAmount().setAmount(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC, PROPERTIES_TRACKER_AMOUNT)); body.getPaymentStatusRequest().getPaymentStatus().getConfirmedAmount().setCurrency(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC, PROPERTIES_TRACKER_CURRENCY));
ActiveOrHistoricCurrencyAndAmount chargeAmountItem = new ActiveOrHistoricCurrencyAndAmount();
chargeAmountItem.setAmount(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC,PROPERTIES_TRACKER_CHARGE_AMOUNT));
chargeAmountItem.setCurrency(returnServiceYamlPropertyValue(yamlProps,TRACKER_SVC, PROPERTIES_TRACKER_CHARGE_CURRENCY));
body.getPaymentStatusRequest().getPaymentStatus().addChargeAmountItem(chargeAmountItem);
return body;
}
Page 24
SWIFT SDK for Java Configuration Management Guide
Legal Notices Copyright SWIFT © 2022. All rights reserved.
Restricted Distribution Do not distribute this publication outside your organisation unless your subscription or order expressly grants you that right, in which case ensure you comply with any other applicable conditions.
Disclaimer SWIFT supplies this publication for information purposes only. The information in this publication may change from time to time. You must always refer to the latest available version.
Translations The English version of SWIFT documentation is the only official and binding version.
Trademarks SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: the SWIFT logo, SWIFT, SWIFTNet, Sibos, 3SKey, Innotribe, the Standards Forum logo, MyStandards, and SWIFT Institute. Other product, service, or company names in this publication are trade names, trademarks, or registered trademarks of their respective owners.
Page 25