SBI Real Time Transaction API

Specifications

CONFIDENTIALITY STATEMENT
No part of this document may be copied, reproduced, stored in any retrieval system, or transmitted in
any form or by any means, either electronically, mechanically, or otherwise without prior written
permission.

Confidential Document Page 1 of 24

Confidential Document Page 2 of 24
Document Details

SBI Rest Web Service Integration Document

Document Name

Document ID SBI/CMP/RealTimeRestService_1

Document Version No. v1.94

Issue Date 1118.1003.20220

Prepared & Maintained

Vipul Shrivastava (AM Sys)
by

Reviewed by Business (TBU)

Owner CMP & SCFU

Classification External

Confidential Document Page 3 of 24

Document History

Version Issue Date Revised By Revision Description

Vipul
1.0 Shrivastava Initial Version
09-03-2020

Sonia Jeswani Changes in Services responses

1.1 09-03-2020
Added Validations

Vipul
1.2 11-03-2020 Added response field description
Shrivastava

Govind
1.3 20-12-2020 Added Error codes for response.
Chaurasia

Govind Added Customer Id & Payment Reference

1.3.1 03-03-2021
Chaurasia No in final JSON request

Govind
1.4 02-08-2021 Added Late Return API details
Chaurasia

Bikas Das Updated logic of fetching Corporate Account

1.5 03-06-2022
number from the Input file

Frankie Text Change in section : “Detailed Sample

1.6 22-06-2022 Nainan Request and Response for Enquiry Services”
And “Payment Data Services Response”

Frankie Response for ‘Enquiry Service’ updated on

1.7 20-07-2022
Nainan page 16,17,18

1.3.2 Response of Enquiry service (remarks

updated)
Steps to Read the response of Enquiry service
(pt 3,4 added)
Frankie 1.3.3 Payments Enquiry service error codes
1.8 21-07-2022
Nainan (table added)
1.3.4 Enquiry service Response (In plain text) -
remarks updated
1.3.5 - Response - remarks - description

Confidential Document Page 4 of 24

 1.2.1 Request Cycle: Product code added in
Frankie
1.9 18-10-2022 the Transaction data
Nainan 1.2.2 Response Cycle: Error Code added “Invalid
Token : TE0012”

Confidential Document Page 5 of 24

Table of Contents
CONFIDENTIALITY STATEMENT..............................................................................................................1
Document Details..................................................................................................................................2
Document History..................................................................................................................................3
SBI Rest Web Service Integrationprocess..............................................................................................6
1. Process flow...................................................................................................................................6
1.1 AUTHENTICATION TOKEN SERVICE.............................................................................................7
1.1.1 Request Cycle.......................................................................................................................7
1.1.2 Response Cycle.....................................................................................................................7
1.2 SBI PAYMENT DATA SERVICE......................................................................................................9
1.2.1 Request Cycle................................................................................................................9
1.2.2 Response cycle............................................................................................................10
1.2.3 Detailed Sample Request/Response of data service.........................................................12
1.2.4 Fields Description of Payment Data service......................................................................13
1.3 SBI ENQUIRY SERVICE...............................................................................................................14
1.3.1 Request Cycle.....................................................................................................................14
1.3.2 Response Cycle...................................................................................................................15
1.3.3 Payments Enquiry service error codes:.............................................................................15
1.3.4 Detailed Sample Request and Response for Enquiry service............................................16
1.3.5 Fields description of Enquiry Service.................................................................................17
1.4 LATE RETURNS API....................................................................................................................17
1.4.1 Request Cycle.....................................................................................................................17
1.4.2 Steps to Read the request of Late return service:.............................................................19
1.4.3 Fields description of Late Return service...........................................................................19
CONFIDENTIALITY STATEMENT..........................................................................................................1
Document Details..................................................................................................................................2
Document History..................................................................................................................................3
SBI Rest Web Service Integration process.............................................................................................5
Process flow...........................................................................................................................................5
AUTHENTICATION TOKEN SERVICE........................................................................................................6
Request Cycle................................................................................................................................6
Response Cycle..............................................................................................................................6
SBI PAYMENT DATA SERVICE.................................................................................................................8

Confidential Document Page 6 of 24

 Request Cycle................................................................................................................................8
Response cycle..............................................................................................................................9
Detailed Sample Request/Response of data service............................................................................11
Fields Description of Payment Data service.........................................................................................12
SBI ENQUIRY SERVICE..........................................................................................................................14
Request Cycle..............................................................................................................................14
Response Cycle............................................................................................................................15
Detailed Sample Request and Response for Enquiry service...............................................................15
Fields description of Enquiry Service...................................................................................................17
LATE RETURNS API...............................................................................................................................17
Request Cycle..............................................................................................................................17
Fields description of Late Return service.............................................................................................19

Confidential Document Page 7 of 24

SBI Rest Web Service Integrationprocess

1. Corporate client would use CMP’s Payment data services for makingpayments. Transaction details
would be sent through secure Web API.
2. This Integration involves 2 web services (a) Payment Data service (b) Enquiry service, both hosted by
SBI.
3. In both the services communication is encrypted at channel level (using TLS 1.2) as well as at payload
level.
4. Access to both the services is token based, there is a token generation method implemented along
with actual service.
5. Client will first request a random token from SBI’s access token service, and the same token will be
used to authenticate while sending the request to Payment data service or Enquiry service.
6. Payment data service alsorequires authorisation for payments to get processedby means ofDigital
Signature.Signaturecan be sent in the Hash Value tag of Payment data service.

1. Process flow

Client API server User Store

Token service request withuserid&password

Validation of userid& password

Token value as response

API response with Token value
response

Data service call withvalid Token in Header

Token, encryption & signature validation

Success/Failure
API response with Success/Failure

Enquiry service call withvalid Token in

Header Token, encryption & reference no validation

Enquiry response against reference

Enquiry API response against reference no.
no.

Confidential Document Page 8 of 24

1.1 AUTHENTICATION TOKEN SERVICE

1.1.1 Request Cycle

AuthenticationTokenService Request Specification: The authentication service is a synchronous service which

will provide a random token to be passed into the header request of the data service. To generatethe token
from the service following steps are to be followed:

1. Generate a random session key.

2. Use AES 128-bit Symmetric Encryption algorithm to encrypt the data of AuthTokenRequest tag with
the randomly generatedsession key.
3. Encrypt Session key using RSA with the public key of SBI and place the encrypted key in SessionKey
tag.
4. Send the same request to Authentication Token Service.

Method: 'POST',HTTP/1.1
URL: 'https://m.fastplusuat.onlinesbi.com:8443/SBITokenService/token/getToken'
Header: {'content-type': 'application/JSON'}
{
"AuthTokenRequest":"em2xEfQIllpAroB9t45VFk9lEkK+PDYpb1iU2oOM4y8Y9VpHLimmI8xbRQ8yxV6HF9NYgV
12gt9z2hSYKnVT0g==",
"SessionKey":"SEuosnLTBib9TNJJcB5yU/3b6F4fRo23YmcoWEzpl77+2uU0d20wfHpSP3r4b95F8UqMj/
SphGaLjMvh0f3m0bnNDXhvC/Jx9WoUwybvWB1uhaSEPAXvKW1UoKYwS475vjbnu4jP0hXUQZ1OFld1xz/
DkhEbJ/rjry7BxVBagwA0olFbwoI+UL/h4ObDWw71NJjpHl8dVt6NxxalvE0VulQCe6ROglSso22zX+YVuTpgOXu4/
AdVZifOmIBNG+0tf6llMzYQzAx+WoNIrxttE0vjfLGNJ8GxigROEIx6weQbzRl/
KUelbsDjfimWi0gbPCYZf1RbbxfalAsYbaAq/g== "
}

Data in AuthTokenRequest Tag: Below sample shows the plain text data in JSON format.

1. When token is requested for payments service “application” will contain the value “PaymentsData”.
2. For Enquiry service value will change to “Enquiry”.

{
"password":"ff0a4f3b85ccb62ac6f60e4a31556b1dbadc4fbcf5f12",
"username":"123456",
"application":"PaymentsData/Enquiry",
“client”:”298989”
}

1.1.2 Response Cycle

Authentication Token Service Response Specification: The response contains a Token (in case of success),
status of request, remarks and error code. The token's type is Bearer which should be sent in header of the
PaymentsData or Enquiry service call. The validity of token expires in 5 mins. Following steps are to be
followed for getting the token from Response of the service:

1. Decrypt the randomly generated session key with the client’s private key using RSA algorithm.
2. The decrypted session key will then be used to decrypt the value of AuthTokenResponse tag using
AES 128 algorithm.

Confidential Document Page 9 of 24

{
"AuthTokenResponse":"otEKHvPilC/uUFzfznLL64hU9/Ad8Rxz7rHpPQWjPMmLs8Db5GtzKBcvb2v764f/
CnsIkVApl9ny\r\nK48GWoCfQAfTVkr8EcP/
BQgle0Zz1hTXRP8mTpgPcPAbk3sBTrCKhbzi6JK5DBrdbHyVdYXPSe0B\r\n5W/DoOTYw2jIWVlXOzo="
"SessionKey":"E9S9ehMBkp19jXPJbHAS6HE4sFoLPfJfoRy3PX1EyNiO0SBnm4g3lusA0POs1ijw9vQ5Am9VU9LJ
mdAp5wilX2C5dPuxvAfH15SFQxtAFwTZZ/oYauUMiY0zqB91D+yw7C4FxS2FOR+nE3kDiTCsE9wDj18g/
GVfIO+HPVHBqFs7CiFRzSQP9aypKnOGRhGN08Kzwl49i2mxP55qHMkUkgqBGfHAmR65tDvslLPCeZ4O2vu4BVw8
KbHQixZsdfAlLIPanzp4m8A13RdwkHGSnNhJUj6/
gSEy0m+3NeK12nTStQ6sST+agdXPbqPjhK5GwoWHFkqjgO3/66ae8PgmVg=="
}

Data in AuthTokenResponse Tag:

1. Decrypted AuthTokenResponse will contain the token value if the request is successful.
2. In case the request is failed token, tag will be blank and code, status & reason will be as per the table
given below.

{
"code":"200",
"remark":"Token successfully generated",
"token":"b8c841e6-ecb9-4b72-9de8-a53034860496:04155",
"status":"OK"
}

Authentication Token Response codes

Sr Status Status Remark/Reason Description

No Scenario code
1 Request Successfully and Validation OK 200 Token successfully generated
Successful
2 Invalid Username & Password ERROR 601 User authentication failed

3 Invalid User Parameters or Null ERROR 602 Token Generation request cannot be
Values parsed
4 Internal Exception ERROR 603 Error in Token Generation Process
5 JSON Parsing Error ERROR 604 Could not parse web service request

Confidential Document Page 10 of 24

1.2 SBI PAYMENT DATA SERVICE

1. The Payment data service is the synchronous service which accepts the actual data for transaction in
the specified JSON format.
2.[1.] It requires the token received from authentication service(1.1 AUTHENTICATION TOKEN
SERVICE), in header part. Requests with Invalid token or expired token will be rejected, and a new
token need to be generated.
3.[2.] The service accepts multiple transactions in one payload using a JSON in payments details tag.
4.[3.] Following is the specification of the service

1.2.1 Request Cycle

Data Service Request Specifications: To access the payment service, Client will first prepare the request in text
format which is then encrypted & digitally signed. Below is the specification of the service.

Data ServiceHeader Specification:

Method: ‘POST’, HTTP/1.1

URL: https://m.fastplusuat.onlinesbi.com/RealTimePaymentService/Payments/
Content-Type': application/JSON
Authorization: Bearer b8c841e6-ecb9-4b72-9de8-a53034860496:04155

Data ServiceBody Specification

Key Name Value Description Sample

CustomerId SBI will shared the
customer Id
{
PaymentReferenceNo Will be unique for "CustomerId": "28xxxx"
each transaction "PaymentReferenceNo":"XXXXX",
Final Request
PaymentRequest Encrypted data "PaymentRequest":"HPttX4u85QiAEV4i=a…..."
request "SessionKey”: "HJEu373eeh9e"
SessionKey Encrypted value of }
AES session key
PaymentDetails Customer’s
{
Payment data
"PaymentDetails”:
which is encoded
{
with Base64
"CustomerId": "28xxxx"
HashValue Contains HashValue
"PaymentReferenceNo":"XXXXX",
generated for
Transaction "DebitAccountNo":"debitAccouNo",
Digital Signature
Data "BeneficiaryName":"beneName",
Or
(To be sent in "BeneficiaryAccountNo":"12578945",
The Checksum
Request Tag "BeneficiaryIFSC":"ICIC0001234",
value using a
of the final "Amount":185596.3,
Hashing algorithm
JSON) "MobileNo":"9561234523",
"EmailID":"XYZ@MS.com",
"Remarks":"remitterToBenefInfo",
“AdditionalField”:”additionalfield”,
“ProductCode”:”DCR/NEFT/RTGS”
}

Confidential Document Page 11 of 24

 "HashValue":"xxxxxxxx”
}

Note: - All key names are mandatory and case sensitive.

For a particular corporate if “Product Code Auto Derivation” flag is enabled, then the Product Code
will be fetched automatically on the basis of “Beneficiary IFSC” code. (In this case the Product Code
value will be empty string)

If “Product Code Auto Derivation” flag is disabled, then the “Product Code” field will be a
mandatory field to pass value.

1.2.1.1 Steps to send the request

1. Prepare the data in specified JSON format of Payment Details.

2.[1.] Generate Signature (Hash Value) of the data in PaymentDetails tag using SHA256withRSA signature
instance.
3.[2.] The signature value is then placed in the HashValuetag of the Transaction Data JSON.
4.[3.] To encrypt the Transaction data JSON, Generate a random 128 bit key.
5.[4.] The data in PaymentDetailsJSON along with the signature hash is thenEncrypted using randomly
generated AES 256 key using cipher AES/GCM/NoPadding.
6.[5.] Create Final Request JSON and add the above encrypted value in the Request tag of the JSON.
7.[6.] Then encrypt the randomly generated key with the public key of SBI using RSA algorithm using
cipher RSA/GCM/PKCS1Padding.
8.[7.] Add encrypted AES key in SessionKey tag of final JSON.
9.[8.] This complete data thus forms a payload request which is to be sent to SBI’s webservice

Note for Debit Account Number:The FastPlus application will pick the debit account number received in the
service request. All the debits will be executed in this same account number for further processing.

1.2.2 Response cycle

Data Service Response Specifications For all successful requests there will be acknowledgement and standard
HTTP 200 response will be sent. While for requests failed due to network issues and bad requests other
standard HTTP responses will be sent (See Reference).

Response Specification:

Key Name Value Description Sample

Ack Json data Acknowledgement of the {
request sent by client "PaymentReferenceNo":"1234",
Status: "CMPReferenceNo":“AO4567895”,
Success/Failure/Pending "Status":"Success/Failure/Pending",
Remarks: Reason for "Remarks":"xxxxx",
Failure/Pending "JournalNo":"123456",
"errorCode":"xxxxx"
}

Confidential Document Page 12 of 24

1.2.2.1 Steps to read the response:

1. In response to the request of client, SBI will provide JSON response as mentioned in
sample response.
2.[1.] This response will be in plain text.

Payments Data service Responses

Sr
Scenario Status Status Code Remark/Reason Description
No
1 Payment Posted Successfully Success SU0000 Completed Successfully
Request Status = Failed due to request parsing errors
2 Unable to decrypt request Failure TE0001 Unable to decrypt request
3 Signature Mismatch or null Failure TE0002 Invalid Hash Value
value received
4 JSON Parsing Error, Data in Failure TE0003 Invalid Request Format
wrong format
Request Status = Failed due to request data validation errors
5 Wrong or null customer ID Failure TE0004 Invalid Customer ID
6 Duplicate Payment Reference Failure TE0005 Duplicate Payment Request
Number.
Note: Combination of
Corporate Id+ Payment
reference number will be
considered for duplication
check
7 Wrong Debit Account Failure TE0006 Invalid Debit Account
Number i.e. A/C Number
received in Payment Request
Vis-à-Vis debit accounts
mapped in system
8 Null check for all field Failure TE0007 Mandatory field missing

9 Product code missing if not Failure TE0008 Product Code cannot be null
opted for auto derivation
11 Debit Account Number Lock Failure TE0010 Please inquire status after some time

12 Any other failure not Failure TE0020 Technical failure. Please contact
mentioned in list support team
13 Invalid token Failure TE0012 Invalid Token

Request Status = Failed at the time of posting in CBS

143 Posting Failure @ CBS Failure BE+ <4 digit CBS Failure message as received from CBS
Error code>
Request Status = Pending

154 Unable to connect to CBS Pending ENQ001 Please inquire status after some time

10 Response not received from Pending ENQ002TE0009 Please inquire status after some time
CBS

Note: In case of any above technical failure scenarios (Status code starts with “TE”), payment
request has to be reinitiated by the client with a same reference number but in case Business failure
(Status code starts with “BE”), payment request has to be reinitiated by the client with a different

Confidential Document Page 13 of 24

reference number. Payment request with same reference number will be rejected by system as
duplicate payment request

1.2.2.2 Exception Cases: API Connectivity Failure

Case 1: Request connection drop

This scenario will be handled @ client end wherein request will have to reposted post connectivity
issue gets resolved.

Case 2: Response connection drop

In this case, client will have to enquire the status using enquiry API. In case client tries to resubmits
the request again, then it will be rejected with failure reason as “Duplicate Payment Request”

Key Management

Both the parties will exchange their PUBLIC KEY in X509 certificate format while private key will
remain with the party itself. However, before expiry of the certificate each party must intimate
the other about expiry.

1.2.3 Detailed Sample Request/Response of data service

Payment Request JSON (In plain text)

{
"PaymentDetails":
{
"CustomerId":"28xxxx",
"PaymentReferenceNo":"XXXXX",
"DebitAccountNo":"debitAccountNo",
"BeneficiaryName":"beneficiaryName",
"BeneficiaryAccountNo":"12578945613",
"BeneficiaryIFSC":"ICIC0001234",
"Amount":185596.3,
"mobileNo":"9561234523",
"emailID":"XYZ@MS.com",
"Remarks":"remitterToBeneficiaryInfo",
“AdditionalField”:”additionalfield”
},
"HashValue":"zc0OvwE/
nNRAhl83r+9FIcjljKCTDWDXvSP3K4B1IEsIUDTdlQrhQTxmNk6gD9u02+MG+BBHvtXioxmmug9FJn1oXxHFJ0Cj3D
kljJrCJgtEuo4fX1qLmWeqRsMF+UkXIqfU+siYjmZlZJAKPfXwXMoej99U+LcXHfV6YSnWPb94RoVsE8eb7l+6u7xsy+f
VRkMhcaQ5xKpuNrHyy"
}

Request String (Encrypted)

{
"CustomerId":"28xxxx",
"PaymentReferenceNo":"XXXXX",
"PaymentRequest":"qx8X9FY93VXmvquaNlE86WMVDciQouMmierQotQl2QqUh2pItlBT/
Na+GnAgMBAAGjITAfMB0GA1UdDgQWBBTSAcEBlxfDqvHGCFfH8s2WoNFMQjANBgkqhkiG9w0BAQUFAAOCAQ
EAZmPh2pRoWmYOWFSqOMozU1XZa3j560ic2wMR7bwMj5IzF+n75vjbABNmgtaZ6bu0OT3g1OHPttX4u85QiAE

Confidential Document Page 14 of 24

V4i6RFLg3p80OdCCpG/slL6BAB6Olf8Cb6qtWWnDDyOWzr",
"SessionKey":"SEuosnLTBib9TNJJcB5yU/3b6F4fRo23YmcoWEzpl77+2uU0d20wfHpSP3r4b95F8UqMj/
SphGaLjMvh0f3m0bnNDXhvC/Jx9WoUwybvWB1uhaSEPAXvKW1UoKYwS475vjbnu4jP0hXUQZ1OFld1xz/
DkhEbJ/rjry7BxVBagwA0olFbwoI+UL/h4ObDWw71NJjpHl8dVt6NxxalvE0VulQCe6ROglSso22zX+YVuTpgOXu4/
AdVZifOmIBNG+0tf6llMzYQzAx+WoNIrxttE0vjfLGNJ8GxigROEIx6weQbzRl/
KUelbsDjfimWi0gbPCYZf1RbbxfalAsYbaA"
}

Confidential Document Page 15 of 24

Response JSON (Encrypted)

{
"PaymentResponse":"qx8X9FY93VXmvquaNlE86WMVDciQouMmierQotQl2QqUh2pItlBT/
Na+GnAgMBAAGjITAfMB0GA1UdDgQWBBTSAcEBlxfDqvHGCFfH8s2WoNFMQjANBgkqhkiG9w0BAQUFAAOCAQ
EAZmPh2pRoWmYOWFSqOMozU1XZa3j560ic2wMR7bwMj5IzF+n75vjbABNmgtaZ6bu0OT3g1OHPttX4u85QiAE
V4i6RFLg3p80OdCCpG/slL6BAB6Olf8Cb6qtWWnDDyOWzr",
"SessionKey":"SEuosnLTBib9TNJJcB5yU/3b6F4fRo23YmcoWEzpl77+2uU0d20wfHpSP3r4b95F8UqMj/
SphGaLjMvh0f3m0bnNDXhvC/Jx9WoUwybvWB1uhaSEPAXvKW1UoKYwS475vjbnu4jP0hXUQZ1OFld1xz/
DkhEbJ/rjry7BxVBagwA0olFbwoI+UL/h4ObDWw71NJjpHl8dVt6NxxalvE0VulQCe6ROglSso22zX+YVuTpgOXu4/
AdVZifOmIBNG+0tf6llMzYQzAx+WoNIrxttE0vjfLGNJ8GxigROEIx6weQbzRl/
KUelbsDjfimWi0gbPCYZf1RbbxfalAsYbaA"
}

Response of the request (in Plain text)

{
"PaymentReferenceNo":"1234",
"CMPReferenceNo":“AO4567895”,
"Status":"Success/Failure/Pending",
"Remarks":"xxxxx",
"JournalNo":"123456",
"errorCode":""
}

Fields Description of Payment Data service

1.2.4 Fields Description of Payment Data service

Request

Fields Name Data type Mandatory Description

CustomerId VARCHAR2(30 BYTE) Yes Corporate id issued by CMP
PaymentReferenceNo VARCHAR2 (30 BYTE) Yes Payment reference number generated
by client
DebitAccountNo VARCHAR2(35 BYTE) Yes Debit Account Number
BeneficiaryName VARCHAR2(180 BYTE) Yes Name of the beneficiary
BeneficiaryAccountNo VARCHAR2(35 BYTE) Yes Credit Account Number
BeneficiaryIFSC VARCHAR2(30 BYTE) No IFSC of Credit Account Number
Amount NUMBER (30,2) Yes Payment Amt
mobileNo NUMBER (10 BYTE) No Mobile Number of beneficiary
EmailID VARCHAR2(50 BYTE) No e-Mail id of beneficiary
Remarks VARCHAR2(30 BYTE) No Remarks entered during payment
request.

Same will be used for narration

Narration will be combination of value

entered in Remarks field + CMP
Reference Number
AdditionalField VARCHAR2(100 BYTE) No Additional field

Confidential Document Page 16 of 24

Response

Fields Name Data type Mandatory Description

PaymentReferenceNo VARCHAR2 (30 BYTE) Yes Unique Reference Number as sent for
transaction
CMPReferenceNo VARCHAR2 (30 BYTE) No SBI CMP’s reference Number
Status VARCHAR(10) Yes Status of transaction
Remark VARCHAR(200) No Status Description
JournalNo VARCHAR(30) No Unique transaction number as appears
on Account statement
ErrorCode VARCHAR(6 BYTES) Yes Error code

Confidential Document Page 17 of 24

1.3 SBI ENQUIRY SERVICE

1. Client can request MIS (again by calling SBI Enquiry API) to get the transaction status using Reference
Number Provided as a response to the Payment Data service.
2.[1.] It also requires the token received from authentication service (1.1 AUTHENTICATION TOKEN
SERVICE), in header part. Requests with Invalid token or expired token will be rejected
3.[2.] SBI would respond to each Web service call to provide current status of the transaction.
4.[3.] Following are the web service specifications (request-response parameters).

1.3.1 Request Cycle

Enquiry service Request Specifications: Client will send the request in JSONformat, which is encrypted, below
is the specification of the request and response for MIS Service along with the token provided earlier, in
header part. Requests with Invalid token or expired token will be rejected, and a new token need to be
generated.

Enquiry Service request Specification for Header:

Method: ‘POST’, HTTP/1.1

URL: https://m.fastplusuat.onlinesbi.com/RealTimeEnquiryService/Enquiry/
Content-Type': application/JSON
Authorization: Bearer 10e6ca3b-be1d-4952-91b7-bf94ff31a44d:004155

Enquiry Service request Specification for Body:

Key Name Value Description Sample

Final Request Request Final encrypted data to {
be placed in the Request “EnquiryRequest”:”cdgj8/UCRcrguj6jGSflMu4f+”
Tag }
Original Data PaymentReference No is {
the unique transaction “CustomerId”:”283467”,
no which was “PaymentReferenceNo”:”123456”
incorporate in payment }
details.
Customer ID is 6 digit
code provided by SBI to
each client.

Steps to send the Enquiry request

1. Client will send the request in JSON format which contains “CustomerCode” (Corporate Id) and
“PaymentReferenceNo”.
2. Complete JSON request will be encrypted with the Public key of SBI using RSA algorithm with cipher
RSA/GCM/OAEPPadding.
3. SBI will decrypt the request by using its own Private Key.

Confidential Document Page 18 of 24

1.3.2 Response Cycle

Enquiry service Response specification: For all successful requests there will be JSON response and
standard HTTP 200 response will be sent. The response of web service will be of 2 type one for
successfully validated and other for validation failed requests. While for requests failed due to
network issues and bad requests other standard HTTP responses will be sent (See Reference).

Response of Enquiry service

Key Name Value Description Sample

Response JSON EnquiryDetails will {
contain the fieldsas "paymentReferenceNo": "1234",
mentioned in Sample "cmpReferenceNo": "AO4567895",
"status": "Success/Failure/Pending",
"remarks": "xxxxxErrorStatusCode|
Remark/Reason",
"journalNo": "123456"
}
{
"PaymentReferenceNo":"1234",
"CMPReferenceNo":“AO4567895”,
"Status":"Success/Failure/Pending",
"ProcessedDate”: “03-03-2020”,
"Remarks":"xxxxx",
"JournalNo":"123456",
"errorCode":""
}

Possible Status Field Values for each transaction:

1. Success
2. Failure
3. Pending

Steps to Read the response of Enquiry service:

1. The response of the service will be in “Encrypted format”.

[1.] SBI will send the response in JSON format which contains
paymentReferenceNoPaymentReferenceNo, ProcessedDate,
cmpReferenceNoCMPReferenceNo, UTR,errorCode, statusStatus, &remarks Remarksand
journalNo.
2. Status will have value either sSuccess, Ffailure or Pending, i
3. The remarks will be a combination of “Status Code and Remarks/Reason Description”
separated with a “|” pipe symbol.f status is success then Remarks field will be blank and if
Status is failure then Remarks field will contain the failure reason.

Confidential Document Page 19 of 24

1.3.3 Payments Enquiry service error codes:

Sr.
Scenario Status Status Code Remark/Reason Description
No
1 Payment Posted Successfully Success SU0000 Completed Successfully
Request Status = Failed due to request parsing errors
2 Unable to decrypt request Failure TE0001 Unable to decrypt request
Request Status = Failed due to request data validation errors
3 Null corporate ID Failure TE0004 Invalid Corporate ID
Wrong or Null payment
4 Failure TE0011 Invalid Payment reference number
reference number
Request Status = Failed at the time of posting in CBS
BE+ <4 digit CBS
5 Posting Failure @ CBS Failure Failure message as received from CBS
Error code>
Request Status = Pending

6 Unable to connect to CBS Pending ENQ001 Please inquire status after some time
Response not received from
7 Pending TE0009 Please inquire status after some time
CBS

Key Management:

Both the parties will exchange their PUBLIC KEY in X509 certificate format while private key will
remain with the party itself. However, before expiry of the certificate each party must intimate the
other about expiry.

1.3.4 Detailed Sample Request and Response for Enquiry service

Original PaymentEnquiryservice Request JSON without Encryption

{
“CustomerCode”:”283467”,
“PaymentReferenceNo”:”123456”
}

Request JSON with Encryption using SBI Public key

{
"EnquiryRequest":”qx8X9FY93VXmvquaNlE86WMVDciQouMmierQotQl2QqUh2pItlBT/
Na+GnAgMBAAGjITAfMB0GA1UdDgQWBBYLF1KEU0pqpQcF9nWiG9wabOrfBvl2QqUh2pItlBT/
Na+GnAgMBAAGjITAfMB0GA1UdDgQWBGnAgMBAAGjITAfMB0GA1UdDgQWAcEBlxfDqvHvukGneVVxgdRzQDS
VDWB7I1KlPbTeAEKeyQInLlXIlkdP1D2TnVBXdrDG4bXK4s7NyVPydJ3NFNVOA2TqPfz87p3U7bWGBj8/
UCRcrguj6jGSflMu4f+hYr83iFL3Txlcg474zms5QqywhWMK3/7yMFVV2avYVLmErQCgRt0JExF5ASh00utcdUm”
}

Enquiry service Response (In plain text)

{
"paymentReferenceNo": "1234",
"cmpReferenceNo": "AO4567895",
"status": "Success/Failure/Pending",
"remarks": " SU0000| Payment Posted Successfully",

Confidential Document Page 20 of 24

"journalNo": "123456"
}
{
"PaymentReferenceNo“: “123456789xxx”,
"CMPReferenceNo“: “AO4567895”,
"ProcessedDate”: “03-03-2020”,
"Status":"Success/Failure/Pending",
"Remarks":"xxxxx",
"JournalNo":"123456",
"errorCode":""
}

ResponseJSON (Encrypted)

{
"paymentResponse":"qx8X9FY93VXmvquaNlE86WMVDciQouMmierQotQl2QqUh2pItlBT/
Na+GnAgMBAAGjITAfMB0GA1UdDgQWBBTSAcEBlxfDqvHGCFfH8s2WoNFMQjANBgkqhkiG9w0BAQUFAAOCAQ
EAZmPh2pRoWmYOWFSqOMozU1XZa3j560ic2wMR7bwMj5IzF+n75vjbABNmgtaZ6bu0OT3g1OHPttX4u85QiAE
V4i6RFLg3p80OdCCpG/slL6BAB6Olf8Cb6qtWWnDDyOWzr",
"sessionKey":"SEuosnLTBib9TNJJcB5yU/3b6F4fRo23YmcoWEzpl77+2uU0d20wfHpSP3r4b95F8UqMj/
SphGaLjMvh0f3m0bnNDXhvC/Jx9WoUwybvWB1uhaSEPAXvKW1UoKYwS475vjbnu4jP0hXUQZ1OFld1xz/
DkhEbJ/rjry7BxVBagwA0olFbwoI+UL/h4ObDWw71NJjpHl8dVt6NxxalvE0VulQCe6ROglSso22zX+YVuTpgOXu4/
AdVZifOmIBNG+0tf6llMzYQzAx+WoNIrxttE0vjfLGNJ8GxigROEIx6weQbzRl/
KUelbsDjfimWi0gbPCYZf1RbbxfalAsYbaA"
}

Confidential Document Page 21 of 24

1.3.5 Fields description of Enquiry Service
Request

Fields Name Data type Mandatory Description

CustomerCode NUMBER (6) Yes Customer code provided by SBI
PaymentReferenceNo VARCHAR2 (30 BYTE) Yes Unique Reference Number as sent
for transaction

Response

Fields Name Data type Mandatory Description

paymentReferenceNo VARCHAR2 (30 BYTE) Yes Unique Reference Number as sent for
PaymentReferenceNo transaction
cmpReferenceNoCMPR VARCHAR2 (30 BYTE) No SBI CMP’s reference Number
eferenceNo
ProcessedDate DATE (DD-MM-YYYY) No Date of processing
sStatus VARCHAR(10) Yes Status of transaction
rRemarks VARCHAR(200) No Status Code and Remarks/Reason
Description separated with a “|” pipe
symbol separated with a “|” pipe symbol
For Eg: “SU0000| Payment Posted
Successfully”Status Description
jJournalNo VARCHAR(30) No Unique transaction number as appears on
Account statement
ErrorCode VARCHAR(6) Yes Error code

1.4 LATE RETURNS API

 Late returns API will be applicable for NEFT & RTGS transactions.
 Client will be host Late returns API at their end.
 For any late return transactions is received in the system, SBI will push the late return status to client
hosted API via SBI proxy server.
 Request will be encrypted using client public key.
 Following are the web service specifications (request parameters).

1.4.1 Request Cycle

Payments Late Returnservice Request Specifications: SBI will send the request in JSON format, which is
encrypted, below is the specification of the request and no response will be received.

Payments Late Return requestSpecification for Body:

Key Name Value Description Sample

CustomerId String SBI will share the {
customer Id "CustomerId": "",
"LateReturn": [
LateReturn Array of JSON Contains the late {
return payment "PaymentReferenceNo": "",
details "DebitAccountNo": "",
"BeneficiaryName": "",
"BeneficiaryAccountNo": "",

Confidential Document Page 22 of 24

 "BeneficiaryIFSC": "",
"Amount": "",
"MobileNo": "",
"Email": "",
"Remarks": "",
"ReturnDate": "",
"Status": "",
"UTR": "",
"ProductCode": ""
},
{
"PaymentReferenceNo": "",
"DebitAccountNo": "",
"BeneficiaryName": "",
"BeneficiaryAccountNo": "",
"BeneficiaryIFSC": "",
"Amount": "",
"MobileNo": "",
"Email": "",
"Remarks": "",
"ReturnDate": "",
"Status": "",
"UTR": "",
"ProductCode": ""
}
]
}

Payment Late Return service Request (Encrypted- AES128withRSA)

{
“LateReturnRequest”:“JlzmiUgpvuaw9MS/9G3HtIa5U0jznTYKUAkxuXRXjsHDTyBAiBJCz54saRp/
UbUV82sTkk2Si7MjRub4u/6L2HJn/
lLqBuiKEd5ZogOdlD5heFZwQQa4H0C0BDzemZFMcDGPkQO+Em3b03z90Z3izGedgaSofIl+/wV3cddUc9Ois/
r1yvuFEGwjjakhx0eKTagaQ8OjSST3n+SX5PyhAX/67OPKLUZk/
WbQKo0KDOjDLvo8oVLWAtZRZNwdB71gdGxB0bOr/2PfNHjTk3k7A2pRXmakguk4fMS+zZIn”,
"SessionKey":"E1ab8hxpHK+UQm4GXhvfXGsSp3XI0wnPbGlsbBUrgkXafx4mpJbLYFkwmYH/ec/
SdEnwMd0Zpq1me056xFcr5bWX7UwAnTWMwqdqf6ZNPJmXB+i2ErHq7Gc1XgsnZrPGZNWsGUnMbyE1iSyHfcY
YvisTH+Zt25+TGa7A1ohi+kXEZg3GL0wzhWYzNt08huklOOilRwqn0zhHKh18ghAiwk4nJRamCbwVzfFzvd2BedJXb
kE0LEtpZohRn6zL0cVHJ6DYLuDNMpP+o2VICNs1ljXlfb2W317gOuPPjo7EfrZxSqi5yHDVjFkQHzMYQtZpg+XgnJVR
nD6OEJk+P8kshw=="
}

1.4.2 Steps to Read the request of Late return service:

1. The whole request would be encrypted using a randomly generated AES 128 algorithm key using
cipher AES/GCM/NoPadding
 Base64 Decoded
 Message Digest – SHA-256

Confidential Document Page 23 of 24

  Encryption Type- AES128
 Cipher to be used- AES/GCM/NoPadding
2. Randomly generated key will be encrypted with client’s public key using RSA algorithm
 Base64 Decoded
 Encryption Type- RSA
 Cipher to be used- RSA/None/OAEPWithSHA1AndMGF1Padding,BC
3. After receiving the request Client must fetch the AES key and decrypt the AES key using his own
private key. The resultant random AES key will then be used to decrypt the remaining data received in
payload.

Key Management:

Both the parties will exchange their PUBLIC KEY in X509 certificate format while private key will
remain with the party itself. However, before expiry of the certificate each party must intimate the
other about expiry.

1.4.3 Fields description of Late Return service

Fields Name Mandatory

CustomerId Yes
PaymentReferenceNo Yes
DebitAccountNo Yes
BeneficiaryName Yes
BeneficiaryAccountNo Yes
BeneficiaryIFSC Yes
Amount Yes
ProductCode Yes
MobileNo No
Email No
Remarks Yes
ReturnDate Yes
Status Yes
UTR Yes

Confidential Document Page 24 of 24