SFMS Bank Application Interface Specifications Document ... - IDRBT

Document Number: 

Copy Number: 

INSTITUTE FOR DEVELOPMENT AND RESEARCH IN 

BANKING TECHNOLOGY 

HYDERABAD 

Structured Financial Messaging System 

SFMS Bank Application Interface Specifications 

Version: 3.0 

Prepared By 

Deccan Park, 

#1 Software Layout, Madhapur, Hyderabad-500 081 

September 2004 

Confidential and controlled document. 

Unauthorised access or copying is prohibited.

SFMS Bank Application Interface Specifications Version 3.0 

DOCUMENT RELEASE NOTICE 

No.: - 3.0 

Client: Institute for Development & Research in Banking Technology, Hyderabad. 

Project: Structured Financial Messaging System (SFMS) 

Document details: SFMS Bank Application Interface Specifications, Version 3.0 

Name Version No. Description 

SFMS Bank Application 

Interface Specifications 

PF3020 

3.0 SFMS Interface with External Bank 

Applications 

Revision details: 

Action taken Preceding 

(add/del/chg Page No. 

) 

New 

Page No. 

Revision 

Description 

Change Register serial numbers covered: 

The documents or revised pages are subject to document control. 

Please keep them up-to-date using the release notices from the distributor of the document. 

These are confidential documents. Unauthorized access or copying is prohibited. 

Approved by: 

Authorized by: 

Date: 

Date: 

Confidential 

Uncontrolled when Printed 

Page i

SFMS Bank Application Interface specifications Version 3.0 

TABLE OF CONTENTS 

CHAPTER 1 – INTRODUCTION.................................................................................. 1 

1.1 BACKGROUND...................................................................................................... 1 

1.2 DEFINITIONS, ACRONYMS, ABBREVIATIONS........................................................ 1 

1.3 ORGANISATION OF THE DOCUMENT ..................................................................... 2 

CHAPTER 2 – BANKAPI ARCHITECTURE.............................................................. 4 

2.1 SFMS BANK APPLICATION INTERFACE ............................................................... 4 

2.2 MESSAGES FLOW ................................................................................................. 5 

2.3 PRE-REQUISITES FOR BANKAPI ........................................................................... 6 

2.4 SOFTWARE REQUIREMENTS ................................................................................. 6 

2.5 HARDWARE REQUIREMENTS................................................................................ 6 

CHAPTER 3 – BANKAPI MESSAGE STRUCTURES ............................................... 7 

3.1 USER MESSAGE.................................................................................................... 7 

3.2 ACKNOWLEDGEMENT MESSAGE ........................................................................ 10 

3.3 NON-DELIVERY WARNING MESSAGE................................................................. 11 

3.4 DELIVERY NOTIFICATION MESSAGE .................................................................. 12 

3.5 OPEN NOTIFICATION.......................................................................................... 12 

3.6 BANKAPI RESPONSE MESSAGE........................................................................ 13 

CHAPTER 4 – BANKAPI USAGE WITH EXAMPLES ........................................... 14 

4.1 REGISTER EXTERNAL BANK APPLICATION ........................................................ 14 

4.2 SET-UP BANK API CLIENT AT EXTERNAL BANK APPLICATION ......................... 14 

4.3 START BANK API SERVER AT SFMS OFFLINE/ONLINE..................................... 15 

4.4 EXTERNAL APPLICATIONS MESSAGE PROCESSING ............................................ 15 

4.5 BANKAPI CLIENT INTERFACE THROUGH COMMAND LINE................................. 16 

4.6 BANKAPI CLIENT INTERFACE THROUGH PROGRAM METHOD............................ 17 

4.7 OVERVIEW OF SFMS BANKAPI USAGE ............................................................ 17 

CHAPTER 5 – LIST OF EXCEPTIONS AND LIMITATIONS ............................... 19 

5.1 LIST OF EXCEPTIONS.......................................................................................... 19 

5.2 LIMITATIONS...................................................................................................... 20 

APPENDIX A – DIGITAL SIGN AND VERIFICATION ......................................... 21 

APPENDIX B – SAMPLE PROGRAM TO CALL BANKAPI CLIENT................. 23 

Confidential 


Page ii


1.1 Background 

CHAPTER 1 – INTRODUCTION 

The SFMS system provides a solution for financial message communication across the 

Indian Financial Network (INFINET). The system enables exchange of messages in a 

highly secured environment. A message structure in SFMS (Structured Financial 

Messaging Solution) has been developed to take care of all kinds of Financial 

Transactions involved in Indian Banking System. The message structure is an adoption of 

an international standard SWIFT with minor modifications to take care of the additional 

messages required for Indian banking needs. The solution will enable the Banks to carry 

out Inter-Bank/Inter-Branch transactions. 

With the Financial Network (INFINET) and a messaging format (SFMS) in place, it is 

envisaged that the Banks will carry out Inter-bank and Intra Bank transactions 

automatically. In order to meet the requirements of Inter-bank and Intra bank 

transactions, we need to have an interface between SFMS and External Applications. 

This document provides the SFMS-External Applications interface Specifications, along 

with the details and functioning of the SFMS-External Applications Integration. 

SFMS API is the application interface for External Bank Applications to send and receive 

messages. This is a part of the SFMS Online / Offline Server software. The document 

provides details about the interface Architecture, Message formats and about the interface 

examples. 

The intended audiences of this document are: 

• Interface Developers of Banks 

• Banking application Vendors 

1.2 Definitions, Acronyms, Abbreviations 

API 

BankAPI 

CA 

CCA 

IDRBT 

IFSC 

INFINET 

LAN 

PDE 

Application Program Interface 

Bank Application Program Interface 

Certifying Authority 

Controller of Certifying Authorities 

Institute for development and Research in Banking Technology 

Indian Financial System Code 

INdian FINancial NETwork. 

Local Area Network 

Possible Duplicate Emission 

Confidential 


Page 1 of 24


PDM 

RA 

RTGS 

SFMS 

SWIFT 

TCP/IP 

TCS 

SMAC 

UMAC 

UNAK 

Possible Duplicate Message 

Registration Authority 

Real Time Gross Settlement 

Structured Financial Messaging System. 

This includes the Branch, Gateway and HUB nodes and the 

communication links between them. 

Society for World wide Inter-bank Financial Telecommunication 

Transmission Control Protocol / Internet Protocol 

Tata Consultancy Services 

This is the MAC generated with node server certificate 

This is the MAC generated with Authorizer’s signature 

This is the User NAK and is generated when the UMAC verification fails 

at the receiving branch. 

1.3 Organisation of the document 

The BankAPI Specifications document is organised into the following chapters 

including this introduction Chapter: 

Chapter 2 

Chapter 3 

Chapter 4 

Chapter 5 

Appendix-A 

BankAPI Architecture 

This chapter provides information about the BankAPI Architecture, 

message flow, Hardware / Software requirements and pre-requites if 

any. 

BankAPI Message Structures 

This chapter provides details about the message structures and 

provides examples. 

BankAPI Usage with examples. 

This chapter explains about BankAPI Server and usage of BankAPI 

client. 

Exceptions and Limitations 

This chapter provides a list of BankAPI Exceptions and Limitations 

in Usage. 

Digital Signing and Verification 

This Appendix provides information about the standards used in 

generation of UMAC. 

Confidential 


Page 2 of 24


Appendix-B 

Sample file to call BankAPI Client 

This Appendix provides a sample program for calling BankAPI 

client method. 

Confidential 


Page 3 of 24


2.1 SFMS Bank Application Interface 

CHAPTER 2 – BANKAPI ARCHITECTURE 

The context diagram for the SFMS – BankAPI solution is depicted below. 

BankAPI Messages 



GW 

GW 

and 

and 

HUB 

HUB 

SFMS On-line / 

Offline with 

BankAPI Server 

SFMS On-Line / 

Offline with 


Bank API - Client 

BankAPI Client 

SFMS architecture primarily consists of the HUB, the Bank Gateway sites and the 

Branch sites connected to one another in a well-defined hierarchy. The HUB and 

the Bank Gateway sites are connected via VSAT communication links / leased 

lines. The Bank Gateways and the Branch Severs can be connected via shared / 

dedicated leased lines or Dial Up lines depending on proximity and the volume of 

traffic. 

In the above architecture, the messages are created from SFMS On-line / Offline 

clients. In general Banks use different Bank applications for internal purposes. 

But, the Bank external application generated messages have to be sent to 

destination branches. For sending messages to destination branches, there should 

be a carrier to carry messages to destination. For supporting the above condition, 

SFMS has provided a secured messages interface module, which is known as the 

BankAPI Interface. 

The SFMS Bank API has the following components: 


Confidential 


Page 4 of 24


The main function of the BankAPI Server is to send and receive messages for 

requests from BankAPI Client. The BankAPI Server continuously runs as a 

demon process and waits to serve BankAPI client requests. 

‣ BankAPI Server validates incoming messages and sends response message 

to BankAPI Client. 

‣ BankAPI server validates user signature with Block 4 content, after 

successful validation, the message is processed. 

‣ BankAPI Server sends set of messages to BankAPI client on request. 

The message formats are discussed in the subsequent chapter. 

BankAPI Client 

The BankAPI client methods / programs are provided to External Application 

interface vendor to call BankAPI Server for purpose of sending and receiving 

messages. 

The functions available with BankAPI client are: 

‣ Send message using file 

‣ Send message as a string 

‣ Receive messages as a string 

Some of the main activities to be carried out for using SFMS – BankAPI are: 

‣ For processing of External Application messages, the external application 

identification has to be registered with SFMS at Online / Offline with unique 

Bank Application ID. 

‣ Setup BankAPI Client as per the instructions provided in subsequent chapters. 

‣ Develop interface with SFMS Bank-API client and External application 

‣ For the purpose of sending and receiving messages from SFMS Online/ 

Offline Server, Start BankAPI Process at SFMS Online-Offline Server 

‣ Send and receive messages from SFMS-BankAPI server using SFMS 

BankAPI Client. 

2.2 Messages Flow 

This section explains the detailed message flow from SFMS BankAPI Server to 

External applications. 

Outgoing Message Flow 

‣ External Application creates the message in SFMS bank application format 

explained in subsequent sections. 

Confidential 


Page 5 of 24


‣ External application invokes SFMS BankAPI Client with arguments having 

message as string or file. This is explained in Application Usage Section. Only 

one message can be sent at a time from the Bank API client to the Bank API 

server. 

‣ SFMS BankAPI Server process running at SFMS Offline / Online server validates 

message and populates the data into SFMS Offline / Online Server on successful 

validation and also sends corresponding response message. The SFMS response 

message structure is explained in subsequent sections. 

‣ During the validation of the message, system verifies for the User Signature 

(UMAC). 

‣ If a message is not signed, then that message will be forced to be in “PENDING 

AUTHORIZATION” state. The user needs to authorize the message at SFMS 

online / offline server manually (using SFMS Application). 

‣ If the message is signed, on successful verification of UMAC the message will be 

kept in ‘TO BE SENT” state in SFMS. If the verification fails, SFMS API returns 

the error code to the external application. 

2.2.1 Incoming Message Flow 

‣ External application invokes SFMS BankAPI Client with receive option. 

‣ SFMS BankAPI Server verifies External application request and sends the 

messages as a string. 

‣ Incoming messages are sent by the Bank API server to the client in chunks of ten 

each. 

‣ Incoming messages are returned in the form of a string with a delimiter $@$. 

2.3 Pre-requisites for BankAPI 

‣ Ensure that SFMS V 3.0 or subsequent version is installed. 

‣ Ensure that Java2 runtime environment with RMI Support is available at External 

Application 

2.4 Software Requirements 

Software Requirements at 

External Application 

Java2 runtime environment 

with RMI Support 

Software Requirements at Offline/ Online 

Server 

No additional software required 

2.5 Hardware Requirements 

No separate Hardware is required for BankAPI Server. SFMS online / offline Server 

can be used for BankAPI Service. 

Confidential 


Page 6 of 24


3.1 User Message 

CHAPTER 3 – BANKAPI MESSAGE STRUCTURES 

The following fields are required for the Bank application in order to generate a valid 

SFMS message. 

Inde 

x 

Mandatory/ 

Optional 

Field Name 

1. M Block A Begin 

Identifier 

2. M Sender Bank 

application 

identifier 

3. M Message 

Identifier 

4. M Input/Output 

Identifier 

5. M Message Type 3 Alpha 

Numeric 

6. M Sub Message 3 Alpha 

Type 

Numeric 

7. M Sender IFSC 11 Alpha 

Numeric 

8. M Receiver IFSC 11 Alpha 

Numeric 

9. M Delivery 

Notification Flag 

10. M Open 

Notification Flag 

11. M Non-delivery 

warning flag 

Field 

Length 

Data 

Type 

Description 

3 Char Block A begin Identifier. This 

should be {A: 

3 Alpha Uniquely identifies the Bank 

Numeric application. 

This is the identifier with which 

Bank application is registered at 

the branch server. 

3 Alpha Application Identifier 

Numeric F01- User to User 

1 Char IO Identifier 

O-Output 

I-Input 

INFINET message type 

INFINET Sub message type. If 

Sub Message Type is blank, 

then fill with XXX. 

IFSC code of the Sender (IFSC 

code to which the bank 

application is registered.) 

IFSC code of the receiver 

1 Number Users to specify whether 

delivery notification is required 

for the message. 

1 – YES 

2 – NO 

1 Number Users to specify whether open 

notification is required for the 

message. 

1 – YES 

2 – NO 

1 Number Flag to inform the user whether 

the non-delivery warning 

message is required or not. The 

possible values are: 1 – Yes 

2 – No 

12. M Obsolescence 

Period 

The default value for nondelivery 

warning flag is ‘2’. 

3 Number Users to specify the period after 

which a non-delivery warning is 

to be sent to the sender, 

applicable only if non-delivery 

Confidential 


Page 7 of 24


13. M MUR (Message 

User Reference) 

14. M Possible 

Duplicate 

Emission Flag 

16 Alpha 

Numeric 

15. M Service Identifier 3 Alpha 

Numeric 

warning flag is specified. 

If Non-delivery warning flag is 

2, then this value should be set 

to ‘000’. 

If Non-delivery warning flag is 

1, then obsolescence value 

should be greater than or equal 

to 002. 

Range of the values for this 

field can be between 002 to 

999. 

This is represented in absolute 

number of units. Each unit is 

internally interpreted as equal to 

5 minutes. 

For example Obsolescence 

period of 003 units is equivalent 

of 15 minutes. 

Bank Application uses this field 

for identifying the message. If it 

is less than 16 then 

concatenated with X. 

1 Number Flag to indicate possible 

duplicate emission 

1 – YES 

2 – NO 

Destination Bank Application 

identifier. 

If not applicable, it should be 

defaulted to XXX. 

16. M Originating date 8 Number Date on which the message was 

created at Bank application – 

(YYYYMMDD) 

17. M Originating time 4 Number Time on which the message 

was created at Bank application 

–(HHMM) 

18. 

19. M Testing and 

Training flag 

20. M Sequence 

Number 

1 Number Flag to indicate test and training 

message. 

1 – YES 

2 – NO 

9 Alpha 

Numeric 

Unique sequence number 

generation by the external 

application for the identification 

of the message in external 

application system. System 

messages for the user messages 

generated by external 

applications will carry this 

Confidential 


Page 8 of 24


21. M Filler 9 Alpha 

Numeric 

22. M UTR (Unique 16 Alpha 

Transaction 

Numeric 

Reference) 

sequence number. SFMS API 

rejects the message if there is 

no sequence number. 

Ex: If sequence number is 5 

then user should send as 

‘000000005’ 

Filler for future use and default 

value is XXXXXXXXX. 

Unique Transaction Reference 

Generated for RTGS. Host 

applications should default it to 

XXXXXXXXXXXXXXXX 

23. M Priority Flag 2 Number This Priority flag is used for 

routing the messages in RTGS 

messages. For Host applications 

the default value is 99 

24. M Block A End 

Identifier 

25. M Block4 Begin 

Identifier 

26. M Block 4 Alpha 

Numeric 

27. M Block End 

Identifier for 

Block 4 

28. O Block5A Begin 

Identifier 

29. O Block 5A Alpha 

Numeric 

30. O Block5A End 

Identifier 

1 Char Block End identifier. This 

should be } 

3 Alpha This block4 begin identifier 

Numeric should be 

{4: 

Text block of the message. 

Length of the message cannot 

exceed 10 KB. 

2 Char Block End identifier should be - 

} 

6 Char It the Bank Application can 

generate the UMAC then this 

should be {UMAC: 

If the Bank Application does 

not have the capability to 

prepare the signature, this field 

can be left blank. 

Authorizer Signature. This is an 

optional field, which can be 

filled by Bank applications with 

signature prepared in PKCS7 

standard on Block4 

Information. 




can be left blank. If this field is 

blank the messages will be 

forced to be in “PENDING 

AUTHORIZATION” state in 

SFMS Offline/Branch Server. 

1 Char If the Bank Application can 

generate the UMAC then this 

should be } 




can be left blank. 

Confidential 


Page 9 of 24


Note: For straight through processing of messages Block 5A is mandatory. 

An example for the incoming message structure to the SFMS branch server from Bank 

application is shown below 

{A: 

Block A begin Identifier 

B09 

Bank Application Identifier 

F01 

Message Identifier 

O Input/output Identifier ( either I or O) 

100 Message type 

XXX 

Sub Message type ( For IFN 298C01, this 

field should be C01, for IFN100 

Message, this field should be XXX) 

SBIN0001001 

Sender IFSC Code 

SBIN0001002 

End receiver IFSC Code 

1 Delivery notification flag 

1 Open Notification flag 

2 Non-delivery Warning flag 

005 Obsolescence Period 

abcdefgh12345678 

Message User Reference (MUR) 

2 Possible Duplicate flag 

XXX 

Service Identifier 

20030909 Originating date 

1020 Originating time 

2 Testing and training flag 

000012345 Sequence Number 

XXXXXXXXXX 

Filler 

XXXXXXXXXXXXXXXX 

Unique Transaction Reference. 

99 Priority Flag 

} Block A end Identifier 

{4: Block 4 Begin Identifier 

:20:TT/320 

Block 4 text message format 

:32A:20030909INR100, 

-} Block 4 End Identifier 

{UMAC: 

Block 5A Begin Identifier 

 

User Signature for Authorisation 

} Block 5A End Identifier 

3.2 Acknowledgement Message 

Index 

Mandato 

ry / 

Field Name 

Field 

Length 

Data 

Type 

Description 

Confidential 


Page 10 of 24


Optional 

1 M Block Identifier 3 Char Block Identifier 

2 M Bank application Identifier 3 Alpha Bank Application Identifier 

Numeric 

3 M Message Identifier 3 Alpha 

Numeric 


F20 – Acknowledgement 

Message 

1 Char Input/Output Identifier 

I – Input 

4 M Input/Output 

Identifier 

5 M Sequence number 9 Number External Application 

Sequence Number for which 

this acknowledgement is 

intended. 

7 M Sender IFSC 11 Alpha 

Numeric 

IFSC code of Originating 

SFMS branch. 

8 M Date and Time 12 Number Date and Time on which 

message is acknowledged 

9 M Block End Identifier 1 Char Block End Identifier 

{A:B09F20O000001000SBIN0001001200103031325} 

{A: 

Block Identifier 

B09 


F20 

Acknowledgment message 

I 

Input/Output Identifier 

000001000 External Application Sequence Number 

SBIN0001001 

Originating IFSC 

200309091023 Date and time on which the sender SFMS Gateway 

acknowledges message 

} Block End Identifier 

3.3 Non-delivery Warning Message 

Index 

Manda 

tory/O 

ptional 

Field Name 

Field 

Length 

Field 

Type 

Description 


2 M Bank application Identifier 3 Char Bank Application Identifier 


Numeric 


F22 - Non-delivery Warning 

message 


Identifier 


I – Input 


Sequence Number . 


Numeric 



8 M Date and Time 12 Numeric Date and Time at which nondelivery 

warning message is 

generated. 


Confidential 


Page 11 of 24


{A: B09F22I000001000SBIN000100200101012227} 

{A: 


B09 


F22 

Non-delivery Warning Message 

I 


000001000 Creation sequence number of the message 

SBIN000100 

Originating IFSC 

200101012227 Date and time on which non-delivery warning message is 

generated. 


3.4 Delivery Notification Message 

Index Mandatory/Option Field Name Field Field Description 

al 

Length Type 


2 M Bank application 3 Alpha Bank Application Identifier 

Identifier 

Numeric 


Numeric 


F23 - Delivery Notification 

message 


Identifier 


I – Input 


sequence number 


Numeric 



8 M Date and Time 12 Number Date and time on which the 

message is delivered. 


{A: B09F23I000001000SBIN0001002000004000} 

{A: 


B09 


F23 

Delivery Notification Message 

I 



SBIN0000002 

IFSC code of Originating SFMS branch. 

200101081730 Date and time on which the message is 

delivered. 


3.5 Open Notification 

Index 

Mandatory/Option 

al 

Field Name 

Field 

Length 

Field 

Type 

Description 

Confidential 


Page 12 of 24



2 M Bank application 3 Alpha Bank Application Identifier 

Identifier 

Numeric 


Numeric 


F24 - Open Notification 

message 


Identifier 


I – Input 


sequence number 

6. M Sender IFSC 11 Alpha 

Numeric 



7 M Date and Time 12 Number Date and time on which the 

message is opened at 

destination. 


{A:B09F24O000001000SBIN000100200101081730} 

{A: 


B09 


F24 

Open Notification Message 

I 



200103032323 Date and time on which message is opened. 

SBIN000100 

IFSC code of Originating SFMS branch. 


3.6 BankAPI Response Message 

Index Mandatory/Option Field Name Field Field Description 

al 

Length Type 

1 M Block Identifier 1 Char Block Identifier Always { 

2 M Return Indicator 1 Char P=Passed 

F=Failed 

3 O Reason Code 10 Alpha 

Numeric 

Reason code for Failure. 

Host applications should 

have the mapping screen for 

mapping these reason codes 

to reason descriptions. 

4 M Block End Identifier 1 Char Block End Identifier. 

Always } 

{FIMRT020021} 

{ Block Identifier 

F 

Failed 

IMRT020021 Failed due to the reason sender IFSC doesn’t exist in IIFSC 

directory. Reasons codes detailed in subsequent sections. 

} Block end identifier. 

Confidential 


Page 13 of 24


CHAPTER 4 – BANKAPI USAGE WITH EXAMPLES 

This chapter gives a detailed explanation about External application registration, SFMS 

BankAPI startup and shutdown and usage of BankAPI Client. 

4.1 Register External Bank Application 

First step in the BankAPI process is the registration of an external application at 

SFMS Offline/ Online Server. The registration process is as follows: 

Click Message Routing Register Bank Application to access the Register 

External Application screen. Enter unique External Application Id, description and 

password to register an External Application. 

The Register screen has the following entries. 

Items 

Description 

External Application Id A Text Box to enter a valid External Application Id. 

External Application Description A Text Box to enter description for an External 

Application 

Password 

A Text Box to enter a Password. 

Click Save button to register the external application. 

Click Reset button to reset values. 

For more information on Bank Application registration details refer to the Offline 

and Online User Manuals. 

4.2 Set-up Bank API Client at External Bank Application 

For sending and receiving messages successfully using Bank API Server, the 

following steps need to be carried out at SFMS Client Server: 

‣ 

‣ 

‣ At SFMS BankAPI client, create a folder by name ‘sfmsbr’ and sub folder by 

name ‘bankapi’ 

‣ Copy BankAPIClient.class, BankAPIImpl_Stub.class, and 

BankAPIInterface.class from C:\SFMS\jakarta-tomcat- 

3.2.3\webapps\ROOT\WEB-INF\classes\sfmsbr\bankapi folder of SFMS Online 

/Offline Server to the bankapi folder at the External Bank Application. 

‣ Set CLASSPATH environment variable to include the class files 

BankAPIClient.class, BankAPIImpl_Stub.class, and BankAPIInterface.class 

Confidential 


Page 14 of 24


‣ Copy BankAPIConfig.properties from C:\SFMS\jakarta-tomcat- 

3.2.3\webapps\ROOT\WEB-INF\classes\sfmsbr\coms\core\utils folder of SFMS 

Online / Offline server to bankapi folder of External BankAPI client server. 

4.3 Start Bank API Server at SFMS Offline/Online 

The following steps are required for executing the Bank API Server: 

‣ The RMI Client will request for reference of component at the Online / Offline 

Server. 

‣ The Registry will send back the reference of component. 

‣ The client will invoke methods (send & receive) of the component 

After successful execution of Bank API server, follow the steps given below: 

‣ Click Start on your Windows desktop. Select Run. 

‣ Enter cmd. Click Ok. 

‣ At the command prompt type rmiregistry and press enter 

‣ Again Click Start on your Windows desktop. Select Run 

‣ Enter cmd. Click Ok. 

‣ At the command prompt type java sfmsbr.bankapi.BankAPIServer and press 

enter. 

Example : C:\>java sfmsbr.bankapi.BankAPIServer 

The message Server Started indicates successful execution of Bank API server. 

4.4 External Applications Message Processing 

External applications can send and receive messages by using the following methods: 

‣ Command line argument 

‣ SFMS BankAPI program method. 

The details of the above process are explained in subsequent sections. 

Confidential 


Page 15 of 24


4.5 BankAPI client Interface through Command Line 

BankAPI File Send Option 

Using this option external applications can send messages as files. 

java sfmsbr.bankapi.BankAPIClient filesend filename.txt 

Example: C:\> java sfmsbr.bankapi.BankAPIClient filesend filename.txt 

Message Send option 

Using this option, external applications can send a message as a string. 

Example: C:\> java sfmsbr.bankapi.BankAPIClient msgsend 

Filename is an optional argument, if the user selects filename, then the status of the 

message will be written to file. Otherwise the status will be displayed on output 

device. 

Message receive option 

For receiving a message from SFMS BankAPI server, the external application 

invokes BankAPI from the command line arguments as 

java sfmsbr.bankapi.BankAPIClient receive 

 

Example: java sfmsbr.bankapi.BankAPIClient receive API BANKAPI 

IFSC0000001 

Filename is an optional argument, if the user selects filename, then the status of the 

message will be written to file. Otherwise the status will be displayed on output 

device. 

IFSC is the IFSC code of the Online/Offline server where the External Bank 

Application has been registered. 

Confidential 


Page 16 of 24


4.6 BankAPI client Interface through Program Method 

SFMS BankAPI client can be called using SFMS BankAPI Client program 

methods. The client method returns a string to the external application. 

The following methods are available for external programming interface: 

‣ executeRemoteProcess(java.lang.String[] args) 

• This method should be called from another program with the 

following arguments to send a message to SFMS BankAPI Server. 

Parameters: 

String - should be either filesend or msgsend or receive 

String - if filesend input absolute path of file, if msgsend input content 

of the message, if receive ExternalApplicationId. 

String - Password. 

String - if receive IFSC. 

‣ getResponse() 

• This method returns the response message when a file is sent. 

‣ getReceivedMessages() 

• This method returns the string of received messages. 

For the sample program provided for developers, refer Appendix B. 

4.7 Overview of SFMS BankAPI Usage 

S.No. Program Arguments Description 

1 BankAPIClient msgsend 

 

 

 

First argument “msgsend” indicates 

that the system is trying to send a 

message in the form of a string. 

Second argument is the string 

containing the actual message to be 

transmitted to SFMS. This method 

will return a string either in file or 

on the output device. The filename is 

an optional argument where the 

2. BankAPIClient Filesend 

 

 

incoming messages are to be saved. 

First argument “filesend” indicates 

that the system is trying to send a 

message in the form of a file. 

Second argument is the string 

containing the filename of the 

message to be transmitted to SFMS. 

This method will return a string 

either in file or on the output device. 

The filename is optional argument. 

Confidential 


Page 17 of 24


3. BankAPIClient Receive 

“receive” argument receives 

messages in the form of a string at 

that instance from SFMS and $@* 

as a delimiter with limit of maximum 

no. of ten messages . 

4. executeRemotePro 

cess (Arguments) 

msgsend 

 

 

Filesend 

 

Receive 

If there are no messages, the system 

gives status as ‘No Messages 

Received’. 

This method will return a string 

either in file or on the output device. 

The filename is an optional 

argument. 

This method is called from another 

program with required Arguments 

and responses will be received by 

calling the following methods: 

For file send / message Send: 

- getResponse() 

For message receive 

- getReceivedMessages() 

Note: Sample program provided at 

Appendix-B. 

Confidential 


Page 18 of 24


5.1 List of Exceptions 

CHAPTER 5 – List of Exceptions and Limitations 

The following are BankAPI Error Messages and their corresponding descriptions 

S No Error Code and Description 

1. PBAPI000000=Message sent successfully 

2. FBAPI000001=Invalid Block-A Begin Identifier. (Prescribed format is {A:) 

3. FBAPI000002=Invalid Sender Bank Application identifier. (eg : APP) 

4. FBAPI000003=Invalid Message Identifier. (eg : F01) 

5. FBAPI000004=Invalid Input/Output identifier. (Always O) 

6. FBAPI000005=Invalid Message Type. (eg 100) 

7. FBAPI000006=Invalid Sub Message Type. (For IFN298C01, this field should be 

C01, for IFN100 message, this field should be XXX) 

8. FBAPI000007=Invalid Sender IFSC. (eg : CNRB0000001) 

9. FBAPI000008=Invalid Receiver IFSC. (eg : CNRB0000001) 

10. FBAPI000009=Invalid Delivery Notification Flag. (either 1 or 2) 

FBAPI000010=Invalid Open Notification Flag. (either 1 or 2) 

11. FBAPI000011=Invalid Obsolescence Period. (Range of values for this filed 

should be between 002 to 999) 

12. FBAPI000012=Invalid Message User Reference (eg: abcdefgh12345678) 

13. FBAPI000013=Invalid Possible Duplicate Emission Flag. (either 1 or 2) 

14. FBAPI000014=Invalid Receiving Bank Application Identifier (eg: TBA if 

present or XXX if not present) 

15. FBAPI000015=Invalid Originating Date.(Format should be YYYYMMDD) 

16. FBAPI000016=Invalid Originating Time.(Format should be HHMM) 

17. FBAPI000017=Invalid Delayed Message Flag.(Either 1 or 2) 

18. FBAPI000018=Invalid Testing & Training Flag. (Either 1 or 2) 

19. FBAPI000019=Invalid Sequence Number or duplicate sequence number. (eg : 

000000001) 

20. FBAPI000020=Invalid Filler. (default should be XXXXXXXXX) 

21. FBAPI000021=Invalid User Transaction Reference.(default should be 

XXXXXXXXXXXXXXXX) 

22. FBAPI000022=Invalid Priority Flag. (Default should be 00) 

23. FBAPI000023=Invalid Block-A End identifier. (should be }) 

24. FBAPI000024=Invalid Block4 Begin identifier. (should be {4:) 

25. FBAPI000025=Invalid Block4. (Length of the message cannot exceed 10 KB) 

26. FBAPI000026=Invalid Block4 End identifier. (Block end identifier should be}) 

27. FBAPI000027=Invalid Block5A Begin identifier.(Should be {UMAC:) 

28. FBAPI000028=Invalid Block5A. 

29. FBAPI000029=Invalid Block5A End identifier.(Should be }) 

30. FBAPI000030=Sender & Receiver IFSC should not be same. 

31. FBAPI000031=Invalid Header Length 

32. FBAPI000100=Invalid UserId. 

33. FBAPI000101=Invalid Password 

34. FBAPI000102=Error in Deformatter. 

35. FBAPI000103=Error in Syntax Check. 

Confidential 


Page 19 of 24


36. FBAPI000104=Error in Conditional rules. 

37. FBAPI000105=Error in Check UMAC. 

5.2 Limitations 

‣ External Bank Applications can send one message at a time through BankAPI. 

‣ External Bank Applications can receive a maximum of 10 messages at a time 

including User and system messages. 

‣ The SFMS BankAPI Server and Client should be on the same Local area network. 

Confidential 


Page 20 of 24


Appendix A – Digital Sign and Verification 

For straight through processing of a message, BankAPI requires Block 5A with UMAC 

information. This section provides information on message signing and algorithms 

required. 

SIGNATURE 

TCS uses PKCS#7 specifications for Digital signatures. This standard describes a general 

syntax for data that may have cryptography applied to it, such as digital signatures and 

digital envelopes. Even though PKCS#7 specification specifies syntax for Signed data, 

enveloped data, signed and enveloped data, encrypted data etc, only PKCS#7 Signed 

Data is used in SFMS. The PKCS#7 data structure is shown below. 

PKCS#7 (CONTENT INFO) 

Content Type 

Content 

Indicates the type of content. It is an object identifier, 

which means it is a unique string of integers assigned by 

the authority that defines the content type. The value set 

by TCS is 1.2.840.113549.1.7.2 

Content. It consists of Signed – data Content Type 

PKCS#7(SIGNED DATA ) 

Version The syntax version number. It shall be 1 

DigestAlgorithms 

Collection of message-digest algorithm identifiers. 

ContentInfo 

The content that is signed. The Content Type value set by TCS is 

1.2.840.113549.1.7.1 and the Content is “NULL” (detached Signature) 

Set Of Certificates 

TCS sets the Signer Digital Certificate 

Set of CRLs 

This optional field is not used by TCS 

Stack of Signer Info 

algorithm ID 

Algorithm identifier 

Parameters 

Algorithm used to sign certificate. TCS 

use either SHA1 or MD5 

Should not be used. 

Signer Info 

Version The syntax version number. It shall be 1 

IssuerAndSerialNumber 

Specifies the signer's certificate 

algorithm ID 

Identifies the message-digest algorithm (and 

Any associated parameters) under which the content and 

Authenticated attributes (if present) are digested. TCS uses 

SHA1 or MD5 algorithm 

AuthenticatedAttributes 

Set of attributes that are signed 

(i.e., authenticated) by the signer. TCS sets the following 

attributes 1) A PKCS #9 content-type attribute having as its 

value the content type of the Content Info value being signed 2) 

A PKCS #9 message-digest attribute, having as its value the 

message digest of the content 3) The signing-time at which the 

signer performed the signing process. 

Confidential 


Page 21 of 24


digestEncryptionAlgorithm 

EncryptedDigest 

unauthenticatedAttributes 

Identifies the digest-encryption algorithm (and any associated 

parameters) under which the message digest and associated 

information are encrypted with the signer's private key. TCS 

uses “RSA Encryption” (1.2.840.113549.1.1.1) 

The result of encrypting the message digests and associated 

information with the signer's private key. 

Set of attributes that are not signed by the Signer. This optional 

field is not used by TCS 

Confidential 


Page 22 of 24


Appendix B – Sample Program to call BankAPI client 

A sample Java Program to call BankAPI server for sending and receiving of external 

application messages is shown below: 

package sfmsbr.bankapi; 

import sfmsbr.bankapi.BankAPIClient; 

public class CallBankAPIClient 

{ 

public static void main(String[] args) 

{ 

String[] arguments = new String[4]; 

String response = ""; 

BankAPIClient bankAPIClient = null; 

if(args[0].equalsIgnoreCase("filesend")) 

{ 

try{ 

//argument specifying FILE SEND process. 

arguments[0] = "filesend"; 

//input file 

arguments[1] = "c:\\APITestMessage.txt"; 

//password 

arguments[2] = "123456"; 

//instantiating BankAPIClient object 

bankAPIClient = new BankAPIClient(); 

//calling executeRemoteProcess method in BankAPIClient class. 

bankAPIClient.executeRemoteProcess(arguments); 

//response msg after executeRemoteProcess method 

response = bankAPIClient.getResponse(); 

System.out.println("response for filesend = "+response); 

}catch(Exception e){} 

} 

else if(args[0].equalsIgnoreCase("msgsend")) 

{ 

try{ 

//argument specifying MESSAGE SEND process. 

arguments[0] = "msgsend"; 

//input message 

arguments[1] = 

"{A:ABCF01O100XXXCNRB0000001CNRB0000002112005abcdefgh123456782APP2003092 

315352000000008XXXXXXXXXXXXXXXXXXXXXXXXXXX}{4:~:20:TRA- 

008~:32A:20040901INR200,~:50:DINESH~HYD~:59:/RAJA~HYD~-}"; 

//password 

arguments[2] = "123456"; 





Confidential 


Page 23 of 24


} 

} 

//response message after executeRemoteProcess method 

response = bankAPIClient.getResponse(); 

System.out.println("response for msgsend = "+response); 


} 

else if(args[0].equalsIgnoreCase("receive")) 

{ 

try{ 

//argument specifying MESSAGE RECEIVE process. 

arguments[0] = "receive"; 

//ExternalApplicationRegistered at Receive side 

arguments[1] = "APP"; 

//password 

arguments[2] = "123456"; 

//IFSC Code at Receiving side. 

arguments[3] = "CNRB0000002"; 





//received messages after executeRemoteProcess method 

response = bankAPIClient.getReceivedMessages(); 

System.out.println("response for Receive = "+response); 


} 

else 

{ 

System.out.println("*****************Usage*****************"); 

System.out.println("incorrect usage:Refer Follow BankAPI client 

Usage"); 

} 

Confidential 


Page 24 of 24

SFMS Bank Application Interface Specifications Document ... - IDRBT

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?