APPLICATION PROGRAMMING
INTERFACE (API) SUITE INTERFACE (API) SUITE
1. Customer Onboarding :
1.1 Overview
The primary objective of this document is to provide our customers a detailed understanding of the offerings of our Corporate API services suite along with necessary information security standards adhered during the integration process.
1.2 Security standards
All APIs available under the present suite follow Asymmetric Encryption algorithm (public-key cryptography).
1.3 Pre-requisites for integration
Following are the pre-requisites from the customer for a seamless onborading process:
i. 1 Certificate Authority(CA) signed public X.509 certificate in PEM format for Two-way SSL purpose
ii. 1 Certificate Authority(CA) signed public X.509 certificate in PEM format as part of public-key cryptography
iii. Public IPs for necessary whitelisting at IOB side
1.4 Onboarding process
The following process illustrates the onboarding process of the customer.
Step1: Submit the onboarding document and complete agreement formalities.
Step1: Submit 2 CA signed x.509 certificates (1 for SSL & 1 for Asymmetric encryption)
UAT/Testing Production
Step2: Submit 2 CA signed x.509 certificates (1 for SSL & 1 for Asymmetric encryption)
Step3: Sign up on UAT Developer portal, subscribe to APIs and receive client id/client secret.
Step4: Perform testing and obtain signoff from IOB.
Step2: Sign up on Production Developer portal, subscribe to APIs and receive client id/client secret.
1.5 Customer Application details
Upon completion of document formalities, the customer shall be able to access the Developer portal of the IOB application, wherein the customer can sign up for the portal and subscribe to APIs. During the process, below mentioned details shall be generated and should be noted by the customer for record.
i. Client id
ii. Client secret
2. Asymmetric Encryption
2.1 Asymmetric Payload encryption
Algorithm and key size
Asymmetric Algorithm for key Encryption
Symmetric Algorithm for Key encryption
Signature Algorithm
RSA-OAEP-256
AES256-CBC
RSA-SHA256
Key Size 256 bits
2.1.1 Steps involved during the life cycle of Request Response:
i. Steps involved during the Request initiation at Client side
Generate 256 bits random key
Encrypt the payload using random key with AES256-CBC algorithm.
Encrypt random key using Bank public key with RSA-OAEP-256 algorithm.
Sign the ciphertext using Client private key using RSA-SHA256 algorithm.
ii. Steps involved during Request processing at Bank side
Bank shall verify the signature using client’s public key
Bank shall decrypt the encrypted random key using Bank private key
Bank shall decrypt the ciphertext using the decrypted random key to receive plain payload
iii. Steps involved during Response initiation at Bank side
Bank shall generate 256 bits random key
Bank shall encrypt the payload using random key with AES256-CBC algorithm.
Bank shall encrypt the random key using Client public key with RSAOAEP-256 algorithm
Bank shall sign the ciphertext using Bank private key using RSASHA256 algorithm.
iv. Steps involved during Response processing at Client side
Client shall verify the signature using Bank public key
Client shall decrypt the encrypted random key using Client private key
Client shall decrypt the ciphertext using the decrypted random key to receive plain payload
2.2 JWS request format
JWS request contains Header, Payload, Signature.
After verification JWS turn into JWE request for the decryption.
JWE request contains Header, encrypted key, IV, ciphertext, Authentication tag.
2.3 Encryption/Decryption
Asymmetric Algorithm for key Encryption RSA-SHA256
Symmetric Algorithm for Key encryption AES256-GCM
Signature Algorithm RSA-SHA256
Key Size 256 bits
Process
JWE Encrypt the payload using IOB certificate shared using KEY algorithm RSA-OAEP-256 and payload encryption algorithm AES256-GCM and JWS sign the resulting encrypted value using RSASHA256 algorithm and API consumer’s private key
2.4 Request headers
2.5 Message format
Consumes : application/json
Produces: application/json
2.6 API Request Format
{ "enc":
"pXkClLExMlUQHXphnESCiGnjF3b3hVKR8AR7op98bG2Vl7js9R3cGa6bOnv nkjhd0sV2tk9aW3VC7GW9VVvQILsT/H6W4JMFYvmpvuqPinuPv+IPMzOV4 ybWfb7Q9JgVh6JwzQdQmGkdlE/Pzhd4tQ=="
2.7 API Response Format
{ "enc":
"3PZIpcqNBgb5ftiwH8ccwqgfpbNxT97LgFrVcGbta46iZkFYXgG0Jek8uTrKzHs NxRG1rd51syHCz6WuEV//vPcY9X9TO2o/vC0JUlN5p6S/oPU3ZJZVA1l43VIbt qqUWmYqNTXyFMeBGKZskteOgXmfJOB8b+vbHAUOjdrlxqQERruw+HhG7Bi SzN496m55w9xQEjGQM7tzrPatIrAyh/i9P0sQ6+dKfZMQbmfL1g05ItoiY/1hfhtj 8ujuAElnAmflnSta5SV+ez+EJBKZTD+WRs2zxifcvY8R/Wll09FSx20kdaDysoHnR mnP/GEIRwnr+im0qTL4hZrU42ruifUXpN9qYJbFfEAZKvIXCko="
3. Specifications for the services
3.1. Intra-Bank (IOB to IOB) Funds Transfer API
This API is used for transfer the amount within IOB accounts.
3.1.1 API Information
API Spec Description
Product Title: Interbank-FT
Name: InterBank-Fundtransfer -API
Version: 1.0.0
3.1.2 Environment Information
API Spec Description
API CATALOG Sandbox
INTERNAL/EXTERNAL
API URL
InterBankF t
Oauth URL
EXTERNAL
https://apigatewaysandbox.iob.in/iob -sb ext/external/IntrabankFT/ intrabank/fundtransfer/v1
https://apigatewaysandbox.iob.in/i ob-sb-ext/external/intrabank-ftoauth/oauth2/token
client id <subscribed application clientid>>
client
Oauth
Version v1.0.0
Format application/json
Method
This API is used for transfer the amount outside IOB accounts.
Product Title:* NEFT/RTGS
Name:* NEFT/RTGS-Fund-Transfer-API
Version:* 1.0.0
API URL NEFT/RTGS
https://apigatewaysandbox.iob.in/iob-sbext/external/neft/rtgs-fund-transfer/neft/rtgs-ft/v1 Oauth URL
https://apigatewaysandbox.iob.in/iob-sbext/external/neft-rtgs-auth/oauth2/token
client id <subscribed application clientid>>
client secret <subscribed application client secret>>
scope NEFT grant type client credentials
Version v1.0.0
Format application/json
3.2.5 Neft/Rtgs - Original Request/Response:
3.2.6 Neft/Rtgs - Postman Collection
3.3 IMPS P2A Transaction API
This API allows users to transfer funds directly to a beneficiary's bank account using details like the account number and IFSC code. Its purpose is to facilitate quick, secure, and seamless real-time interbank fund transfers.
3.3.1 API Information
3.3.2 Environment Info
API URL P2A
https://apigatewaysandbox.iob.in/iob-sbext/external/imps/p2a/transaction/v1
https://apigatewaysandbox.iob.in/iob-sbext/external/imps/oauth2/token
client id <subscribed application clientid>>
client secret <subscribed application client secret>>
scope P2A grant
Version
Format
Your a/c no. XXXXXXXX4667 is debited for Rs. 15.00 on 10/12/19 and a/c XXXXXXX - (a/c holder name - kiran) credited. (IMPS reference no. 934413490606)
vailBal Alpha Numeric 20 O 1885.01 beneName Alpha Numeric 20 O kiran
Your a/c no. XXXXXXXX4667 is debited for Rs. 15.00 on 10/12/19 and a/c XXXXXXX(a/c holder name - kiran) credited. (IMPS reference no. 934413490606). smsMessag e
Your a/c no.XXXXXXXX4667 is debited for Rs. 15.00 on 10/12/19 and a/c XXXXXXX - (a/c holder name - kiran) credited. (IMPS reference no. 934413490606).
CBS-AccountStatement-APIv2
The CBS AccountStatement API retrieves account transaction details with pagination and without pagination, enabling efficient, scalable, and filtered data access for seamless integration with banking systems.
3.4.1 API Information
Product
3.4.2 Environment Info
API URL A/C Statement
https://apigatewaysandbox.iob.in/iob-sbext/external/cbs/accountstatement/v2
URL https://apigatewaysandbox.iob.in/iob-sbext/external/accountstatement/v2/oauth2/toke
client id <subscribed application clientid>>
client secret <subscribed application client secret>>
scope Accounts
grant type client credentials
Format application/json Method
17 lastTxnId Empty or <10
18 lastTxnSrlNo Empty or <10 String
Conditional if paginationDe tails is passed
Conditional if paginationDe tails is passed
19 txnType 1 String Optional
20 sortIn 1 String Optional
3.4.4 AccountStatement - Response Parameters
FieldName
RequestUUID String
ChannelId String
Unique identifier for the request.
Identifier for the channel making the request.
Length: 16-32, Alphanumeric, No < or >
Length: ≤6, Uppercase letters only
Body Object Contains the main response data. Required
PaginatedAccou ntStatement Object Contains account balances and transaction details. Required
accountBalances Object Details of the account balances. Required
acid String Account ID. 15-16 digits only availableBalance .currencyCode String Currency code for the available balance. 3 uppercase letters
FieldName Data Type Description Mandatory
fFDBalance.amount Value String Forward Float balance amount.
Up to 10 digits with optional 2 decimal places
fFDBalance.currency Code String Currency code for Forward Float balance. 3 uppercase letters
floatingBalance.amo untValue String Floating balance amount.
Up to 10 digits with optional 2 decimal places
floatingBalance.curr encyCode String Currency code for Floating balance. 3 uppercase letters
ledgerBalance.curre ncyCode String Currency code for ledger balance. 3 uppercase letters
userDefinedBalance. currencyCode String Currency code for user-defined balance. 3 uppercase letters
field125, field126, field127 Object Reserved or additional fields. Optional
hasMoreData String Indicato if more data exists for pagination. Empty or Booleanlike values
transactionDetails Array of Objects List of transactions. Required
pstdDate String (ISO 8601) Posted date of the transaction. Format: YYYY-MMDTHH:mm:ss.sss
transactionSummary Object Summary of the transaction details. Required
transactionSummary. instrumentId String Identifier for the transaction instrument. Optional, Can be empty
FieldName Data Type Description Mandatory transactionSummary.
txnAmt.amountValue String Transaction amount.
Up to 10 digits with optional 2 decimalplaces transactionSummary.
txnAmt.currencyCod e String
Currency code for the transaction amount. 3 uppercase letters transactionSummary.
txnDate String (ISO 8601) Date of the transaction.
Format: YYYY-MMDTHH:mm:ss.sss transactionSummary.
txnDesc String Transaction description. Optional transactionSummary.
txnType String
Type of transaction (C for credit, D for debit). 1 character only transactionSummary. addtnlData Object
Additional data related to the transaction. Optional
txnBalance.amountV alue String Balance after the transaction. Up to 10 digits with optional 2 decimalplaces
txnBalance.currency Code String Currency code for the transaction balance. 3 uppercase letters
txnCat String Transaction category. Optional
txnId String Transaction ID. Alphanumeric, Up to 10 characters
txnSrlNo String Transaction serial number. Numeric, Up to 10 digits
valueDate
String (ISO 8601)
Value date of the transaction. Format: YYYY-MMDDTHH:mm:ss.sss
getFullAccountSt atementWithPa gination Custo mData Object Custom data related to the account statement. Optional THB String Additional custom data field. Optional
3.5.1 API Information
3.5.2 Environment Info
API URL https://apigatewaysandbox.iob.in/iob-sbext/external/cbs/fetch/ministatement/v1
Oauth URL https://apigatewaysandbox.iob.in/iob-sbext/external/ministatement/oauth2/token
3.5.4 MiniStatement
Parameter
getMiniAc countStat ementRes ponse
500 Array List {} [length]
getMiniAccountStatementResp onse
{ MiniStatementSummary
{ accountSummary
{ acid[15], availableBalance
{ amountValue[20,4], currencyCode[3]
} branchId[4], currencyCode[3], fFDBalance
{ amountValue[20,4], currencyCode[3]
} floatingBalance
{ amountValue[20,4], currencyCode[3]
} ledgerBalance
{ amountValue[20,4], currencyCode[3]
} userDefinedBalance
{ amountValue[20,4], currencyCode[3]
} }accountTransactionSummary
{ instrumentId[12], txnAmt
{ amountValue[20,4], currencyCode[3]
} txnDate[25], txnDesc[50], txnType[1] } } } TRUE
AccountSumm ary
Details: Account Number, Available Balance (Amount, Currency), Branch Code, Currency Code, FFD Balance, Floating Balance, Ledger Balance, User defined Balance Account Transaction Summary
Details: Instrument ID, Transaction Amount (Amount, Currency), Transaction date, Transaction Description, Transaction Type
Token URL
Token Scope
Version
Method
https://apigatewaysandbox.iob.in/iob-sbext/external/cbs/fetch/imps-transactions/v1
https://apigatewaysandbox.iob.in/iob-sbext/external/imps-transactions/oauth2/token
3.6.3 Fetch-IMPS-Transactions - Request Parameters
FIXML HEADER
RequestUUID 16-32 String Mandatory 1931b4974792229300
ChannelId 01-Jun String Mandatory
FIXML BODY
requestID Aug-32 String Mandatory
userID 05-Oct String Mandatory
makerID 05-Oct String Optional
checkerID 05-Oct String Optional
acno 15-15 String Mandatory Account Number
fromdate 10 Date Mandatory
todate 10 Date Mandatory
Value From Date Ex: 01-01-2023
Value To Date Ex: 0101-2023
3.6.4 Fetch-IMPS-Transactions - Response Parameters
requestID
errorCode 10 String Optional Error code in case of failure
Parameter
remarks 100 String TRUE Remarks
crm 500 Array List {} [length] { sol [10], valuedt[15], arttrantype [10],ccy[10], amount[20, 2],tranpartic ular[250], lchgtime[50 ], msgrrn[100], ranid[25], trandt[25] }
TRUE
Tran
SOL ID, Value Date, Part Tran Type, Tran Currency Code, Tran Amount, Tran Particular, Last Changed Time (DD-MMMYYYY HH:MM:SS), Message RRN, Tran ID, Tran Date
3.6.5 Fetch-IMPS-Transactions - Original Request/Response
3.6.6 Fetch-IMPS-Transactions - Postman Collection
3.7.1 API Information
Product Title:*
3.7.2 Environment Info
Fetch-NEFT-RTGS-Transactions-API
API URL
Token URL
Token Scope
https://apigatewaysandbox.iob.in/iob-sbext/external/cbs/fetch/neft-rtgs-transactions/v1
https://apigatewaysandbox.iob.in/iob-sbext/external/neft-rtgs-transactions/oauth2/token
3.7.3 Fetch-NEFT-RTGS-Transactions - Request Parameters
FIXML
BODY
requestID Aug-32 String Mandatory
userID 05-Oct String Mandatory
acno 15-15 String Mandatory Account Number
fromdate 10 Date Mandatory Value From Date Ex: 01-01-2023
todate 10 Date Mandatory Value To Date Ex: 01-01-2023
paysysid 5 String Mandatory Paysys ID – NEFT (or) RTGS
3.7.4 Fetch-NEFT-RTGS-Transactions - Response Parameters
Parameter
crm 500 Array List {} [length] { SOL ID [8], lchgtime [15], valuedt [15], trandt [15], tranid [9], parttrantype[1], tran crncy code [3], amount [20,4], Bank [50], UTR [50], tranparticular [50], TRAN RMKS OUTWA RD IFSC [30], INWARD Routing R ef Num[20] }
TRUE
SOL ID, Last changed Time, Value Date, Tran Date, Tran ID, Part Tran Type, Tran Currency Code, Tran Amount, Bank, UTR, Transaction particular, Tran remarks outward IFSC, Inward routing reference number
3.7.5 Fetch-NEFT-RTGS-Transactions - Original Request/Response
3.7.6 Fetch-NEFT-RTGS-Transactions - Postman Collection
API
Token URL
https://apigatewaysandbox.iob.in/iob-sbext/external/cbs/issue/chequeservice/v1
https://apigatewaysandbox.iob.in/iob-sbext/external/issuechequeservie/oauth2/token
Parameter Length Data Type Mandatory /Optional Description
FIXML BODY
requestID 16-32 String Mandatory
userID 10 String Mandatory
makerID 10 String Mandatory
checkerID 10 String Mandatory
accountN umber 15 String Mandatory
chequeBo okType 10 String Mandatory SB20 SBA 20 LEAVES
CA50 CAA 50 LEAVES
CC50 CCA 50 LEAVES
CA100 CAA 100 LEAVES
CC100 CCA 100 LEAVES
SB20A SBA 20 LEAVES VIA ADC
CC50A CCA 50 LEAVES VIA ADC
CA50A CAA 50 LEAVES VIA ADC
noOfLeav es 01-May Number Mandatory Multiples of Cheque Book Type
crossType 02-Mar String Mandatory NN – Not Negotiable
brcode 04-May String Mandatory Branch Code of the userID
3.8.4 IssueChequeService - Response Parameters
Parameter Length
requestID String Mandatory
Parameter
Status String TRUE SUCCESS/FAILURE
errorCode String
errorDescripti on String
Optional (if no error observed) Error code in case of failure
Optional (if no error observed) Error description
remarks String TRUE Remarks
3.8.5 IssueChequeService - Original Request/Response
3.8.6 IssueChequeService - Postman Collection
4.1 ESB Response codes
Error Codes Description
ESB-200 Success
ESB-ERR-100 Invalid Account Number
ESB-ERR-101 Invalid CIF ID
ESB-ERR-102 Invalid IFSC code
ESB-ERR-104 SMS Generation Error
ESB-ERR-105 SMS Generation Error
ESB-ERR-106 Account Validation Failure
ESB-ERR-107 OTP Expired
ESB-ERR-108 Invalid OTP
ESB-ERR-109 Session Expired
ESB-ERR-110 Invalid Session
ESB-ERR-111 No active session
ESB-ERR-112 In valid Account number
ESB-ERR-113 Account Authentication Failure
ESB-ERR-125 Token Error