QR Api
QR Api
QR Api
QR/Intent
Contents
Introduction ......................................................................................................................................................... 3
API Details ........................................................................................................................................................... 4
1. API Name: QR API ...................................................................................................................................... 5
2. API Name: Callback.................................................................................................................................... 7
3. API Name: Transaction Status ................................................................................................................. 8
4. API Name: Callback Status ..................................................................................................................... 10
5. API Name: Refund API ............................................................................................................................ 12
6. Error Codes ................................................................................................................................................ 14
Security .............................................................................................................................................................. 17
Encryption & Decryption Process ................................................................................................................. 18
Introduction:
UPI is a set of APIs created by NPCI to facilitate online immediate payments. UPI is expected to
further propel easy instant payments via mobile. The payments can be both sender (payer) and
receiver (payee) initiated and can be carried out using virtual payment addresses, Aadhaar
integration, mobile number etc. The payer’s smartphone could be used for secure credential
capture.
Merchant on-boarding:
Merchant needs to provide the following information for onboarding of UAT and production
environment:
Technical list:
IP address (For dynamic IPs please provide range of IP addresses)
Merchant call-back URL to post final transaction status from ICICI’s end
Merchant certificate with 4096 bits public key (.pem or .cer format) for encryption
Merchant SSL certificate for sending call back response on call back url
Once the merchant provides all the above mentioned technical list, Bank will do the necessary
configuration at their end and provide Merchant ID (MID) which shall be configured against the
Virtual Payment Address (VPA). Once these details are received at merchant’s end, they can start
the API testing.
Bank will also provide ICICI bank’s public key certificate for encryption to be done at merchant’s
end. Merchant will need to make encrypted request call using ICICI Bank’s public key certificate to
selected APIs from their Application Server and ICICI Bank will post encrypted response packet
using merchant’s public key certificate. Merchant is required to decrypt the response packet
received at their end with the corresponding private key.
General Flow:
1. For QR code or intent call transactions, merchant needs to send ‘refid’ in “tr” field of the
QR/intent string.
2. There are two ways to generate ‘refid’.
First, is to call QR API. Merchant will send QR API request to QR API.On receiving request
in correct format, ICICI bank will send QR API response which will have unique RefId
starting with EZY or EZP prefix.
Second way, merchant will generate its own ‘refid’ with merchant specific three Prefix
letter.
3. Using ‘refId’ merchant can create QR code or can initiate intent call. Customer will scan QR
code or in case of intent call, customer will choose his PSP app to complete transaction.
4. Once Customer accepts or rejects the request from his mobile app, ICICI bank will send call
back response to merchant stating Success or Reject on their callback URL.
5. When customer accepts the request from his mobile, transaction will be completed and
amount will be credited to merchant’s account.
6. For ‘refid’ generated through QR API ICICI bank will send respective ‘merchantTranId’ of QR
API request in call back response.
7. For merchant generated ‘refid’, ICICI bank will send merchant generated ‘refid’ in call back
response except prefix letter.
API Details:
The specific name of each APIs are mentioned in the below sections. The customer parameters
to be passed are specific to each API.
First the parameters and their values will be entered in JSON Object. Then the whole JSON object
will be encrypted and then encoded. Finally, the whole request will be passed through URL.
[GatewayURL(Base64Encode(RSA_Encrypt(JSON_Object{Field_Elements(field1,field2,…)})))]
The JSON Request Object is mentioned below where complete payload is encrypted using the
public key provided by ICICI Bank:
Encryption needs to be done using RSA 4,096 bits public key provided by ICICI Bank.
While sending the request please add the Headers in CODE which are Highlighted:
X30i3+Y5kWiuQQ6/d+pW6oJaMidDpaXLznH03XUm6xRlUeAhKTghFb2SeXHzyNCkoi2+Ci8ms2OU
ljUhsJTyLWo+N6INqMNpki3ieQWBAxo+8s/xc9t/SSp3eLUIPgcEnwHJ93tDnvzD8KjRtWqo3mBg
ja84TnQvISM918WcUvZQi/NLbGjxlemBm2bHJYSfJwVtTMbJubvlZmAhrW14YpfY6B8ZzUBujZhf
qldMLL+B+zyKd9tlTztVCeVINQvDPhsNnU9OBNN+sHIESZzzi+B7PgYn7n/Mzpo594npZbZ9sDwS
XdwMlK1KY3rJXfzoq+RZL+dcl1ftfZjlqCHFfHposHzB3C3Smjm9EnzZEB0DfnxnT5CHvWM8l90I
1CKew9ZjKrbHAQ6y1eKDKad9935TlSh/WTirdtDHcpJW+HC8NYzd5lwzuVyWr24JD+riS7DcnKv7
YDH4xxnHaWXx/g8tgsxWK4H2m+VdvivVKWzAaX4GeNZd76uxGGUvKwxgqiyLasFqtYzYjOIm8fRq
jGpDdQ9CkrdmvyOOdOV+qFbXaMxCLyBAlrarFGO4QWoO5oJvmWY6zOXa/A2Apx+IX7CG51VuiwQZ
ssVEAGVzHQYn1n69nf2Jj/LLJXbg9gFg9naHTwf2m9jBorUhoo007Cm87v5oytwzGJIX13VOIAY=
1. API Name: QR API
Description: QR API will be used to fetch ‘refid’ from ICICI system. This ‘refid’ will be used to
generate QR/ intent string.
As an optional feature, Validation of the Debit Account can be done using Validate Payer Acc
Flag, Payer Account and Payer IFSC parameter.
UAT Endpoint:
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/QR3/{merchantId}
Live Endpoint:
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/QR3/{merchantId}
Input Parameters:
Mandatory
Name Type Description (Y-Yes / O- Length
Optional)
merchantId Number Merchant Identification Y 10
Number
terminalId Number Needs to send Merchant Y 4
category code (MCC code).
[Default MCC-5411]
amount Number Amount to be debited (In Y 20
Rupees) in Integer value
with 2 decimal
E.g. : ‘200.00’ or ‘300.12’
merchantTranId AlphaNumeric This will be a Transaction ID Y 35
generated by the API and
should always be unique
billNumber AlphaNumeric Bill Number / Order Number Y 50
validatePayerAccFl String ‘Y’ for validating debit a/c O 1
ag details or ‘N’ for non-
validation
payerAccount Number When ‘validatePayerAcc’ O
Flag is ‘Y’ then it is
mandatory. Payer Account
number is required to be
entered.
payerIFSC AlphaNumeric When ‘validatePayerAcc’ O
Flag is ‘Y’ then it is
mandatory. Payer IFSC code
is required to be entered.
Sample Packet:
{
"amount": "5.00",
"merchantId": "118449",
"terminalId": "5411",
"merchantTranId": "p0nillp0k9lqlp091p17",
"billNumber": "sdf1po111b",
"validatePayerAccFlag": "Y",
"payerAccount": "0405012740",
"payerIFSC": "IC00000",
}
Output Parameters:
Response Packet:
{
"response":"0",
"merchantId":"118449",
"terminalId":"5411",
"success":"true",
"message":"Transaction Initiated",
"merchantTranId":" p0nillp0k9lqlp091p17",
"refId":"EZY286844327832
}
Example: upi://pay?pa=abc@icici&pn=Abc&tr=EZY123456789012&am=10&cu=INR&mc=5411
2. API Name: Callback
Description: Final transaction response posted by ICICI Bank to Merchant’s callback URL.
Parameters:
{
"merchantId" : "106161",
"subMerchantId" : "12234",
"terminalId" : "5411",
"BankRRN" : "615519221396",
"merchantTranId" : "612411454593",
"PayerName" : "hhjjj",
"PayerMobile" : "8879770059",
"PayerVA" : "testing1@imobile",
"PayerAmount" : "12",
"TxnStatus" : "SUCCESS",
"TxnInitDate" : "20160715142352",
"TxnCompletionDate" : "20160715142352"
}
3. API Name: Transaction Status
Description: This API will be used by Merchant to get the status of the transaction based on
‘merchantTranID’ input parameter. This API will fetch the updated status from NPCI.
UAT Endpoint:
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/TransactionStatus3/{merchantId}
Live Endpoint:
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/TransactionStatus3/{merchantId}
Input Parameters:
Mandatory Length
Name Type Description
(Y/N)
merchantId Number Merchant Identification Y 10
Number
subMerchantId Number Sub Merchant Identification Y 10
Number of Merchant
terminalId Number Needs to send Merchant Y 4
category code (MCC code).
[Default MCC-5411]
merchantTranId AlphaNumeric This will be a Transaction ID Y 35
generated at the time of
original request
Sample Packet
{
"merchantId": "118449",
"subMerchantId": "118449",
"terminalId": "5411",
"merchantTranId": "p0nillp0k9lqlp091p17"
}
Output Parameters:
Sample Response:
{
"response" : "0",
"merchantId" : "106161",
"subMerchantId" : "12234",
"terminalId" : "5411",
"OriginalBankRRN" : "615519221396",
"merchantTranId" : "612411454593",
"amount" : "12",
"success" : "true",
"message" : "Transaction Successful",
"status" : "SUCCESS"
}
Current response:
PENDING, SUCCESS, FAILURE
4. API Name: Callback Status
Description: This API will be used by Merchant to get the status of the transaction by passing
correct transaction type. This API will fetch the status of the transaction based on RRN or
merchant transaction ID or ref-id from ICICI Switch.
UAT Endpoint:
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/CallbackStatus2/{merchantId}
Live Endpoint:
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/CallbackStatus2/{merchantId}
Input Parameters:
Mandatory
Name Type Description Length
(Y/C)
merchantId Number Merchant Identification Y 10
Number
subMerchantId Number Sub Merchant Identification Y 10
Number of Merchant
terminalId Number Needs to send Merchant Y 4
category code (MCC code).
[Default MCC-5411]
transactionType Alphabet Flag to identify type of Y 1
original transaction as C, R, Q
or P as per below mentioned
*table
merchantTranId AlphaNumeric This will be a Transaction ID C 35
generated at the time of
original request.
transactionDate Date Date of the Transaction C 20
BankRRN Number Bank Reference Number of C 15
the original transaction
refID AlphaNumeric Reference Number passed in C
QR/Intent Call
{
"merchantId": "118449",
"subMerchantId": "118449",
"terminalId": "5411",
"transactionType": "C",
"merchantTranId": "p0nillp0k9lqlp091p17"
}
Output Parameters:
Sample Response:
{
"response" : "0",
"merchantId" : "106161",
"subMerchantId" : "12234",
"terminalId" : "5411",
"OriginalBankRRN" : "615519221396",
"merchantTranId" : "612411454593",
"Amount" : "12",
"payerVA" : " testing1@imobile ",
"success" : "true",
"message" : "Transaction Successful",
"status" : "SUCCESS",
"TxnInitDate" : "20160715142352",
"TxnCompletionDate" : "20160715142352"
}
5. API Name: Refund API
Description: This API needs to be used by Merchants to initiate refunds of the transactions. Both
offline and online refunds are supported in the same API.
UAT Endpoint:
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/Refund/{merchantId}
Live Endpoint:
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/Refund/{merchantId}
Input Parameters:
Mandatory Length
Name Type Description
(Y/N)
merchantId Number Merchant Identification Y 10
Number
subMerchantId Number Sub Merchant Identification Y 10
Number of Merchant
terminalId Number Needs to send Merchant Y 4
category code (MCC code).
[Default MCC-5411]
originalBankRRN String Original Transaction Id Y 15
merchantTranId String Refund Transaction Id Y 35
originalmerchantTr AlphaNumeric Merchant TranID of Refund Y 35
anId transaction.
refundAmount Number Amount to be debited.(In Y 20
Rupees, Integer value with 2
decimal)E.g. : 200.00 / 300.12
payeeVA AlphaNumeric Alias name with which the N 255
payee can be identified by his
registered entity.
Note AlphaNumeric Remarks entered by the payer Y 50
for his reference.
onlineRefund String Refund request mode – Online Y 1
or Offline refund – ‘Y’ for
online refund and ‘N’ for
Offline refund
Sample Packet:
{
"merchantId": “106092”,
"subMerchantId": “12234”,
"terminalId": “2342342”,
"originalBankRRN": "622415338172",
"merchantTranId": "88442047",
"originalmerchantTranId": "202020202021",
"payeeVA": "yatin@imobile",
"refundAmount": "10.00",
"note": "refund-request",
"onlineRefund": "Y"
}
Output Parameters:
Sample Response
{
"merchantId": “106092”,
"subMerchantId": “12234”,
"terminalId": “2342342”,
"success": "true",
"response": “0”,
"status": "SUCCESS",
"message": "Transaction Successful",
"originalBankRRN": "622415338172",
"merchantTranId": "88442055"
}
6. Error Codes
API Key needs to be passed in every request in the header and merchant IP
will also be required for IP whitelisting.
API Key needs to be passed in the parameter name: apikey
API request and response to Merchant is secured using advanced and
agreed upon encryption algorithm agreed to maintain data confidentiality
and integrity.
API Gateway uses the standard authenticating and authorizing process for
the incoming request from merchant and for maintaining the integrity and
confidentiality we apply state of art Encryption/ Decryption algorithm.
Encryption & Decryption Process:
For Encryption of a payload at Client’s end.
encryptedKey = Base64Encode(RSA/ECB/PKCS1Encryption(SesionKey,ICICIPubKey.cer))
Session key is nothing but randomly one time generated string of length 16 (OR 32).
encryptedData = Base64Encode(AES/CBC/PKCS5Padding(Response,SessionKey))
IV= getFirst16Bytes(Base64Decode(encryptedData)
SessionKey =
Base64Decode(RSA/ECB/PKCS1Decryption(encryptedKey,ClientPrivateKey.p12,)) Session
key is nothing but randomly generated string of length 16 (OR 32) .
Response = Base64Decode (AES/CBC/PKCS5Padding Decryption(encryptedData,SessionKey,
IV))
1. Get the IV- Base64 decode the encryptedData and get first 16 bytes and rest
is encryptedResponse.
bytes[] IV= getFirst16Bytes(Base64Decode(encryptedData)