Collect API
Collect API
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. Merchant will send Collect Pay request on collect pay API. Merchant will send customer’s
VPA and other transaction details.
2. On receiving request in correct format, ICICI bank will send collect pay response as
‘transaction initiated successfully’.
3. At the same time UPI request will be sent to customer’s PSP (based on his VPA) mobile
app. (E.g. xyz@icici VPA request on iMobile App and for other banks VPA i.e. xyz@axisbank,
on their respective mobile app)
4. Once Customer ‘accepts’ or ‘rejects’ the request from his mobile app, ICICI bank will send
‘Callback’ response to merchant stating ‘Success’ or ‘Reject’ on the 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. At any given time, merchant can check the status of transaction by calling Transaction status
API.
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: Collect Pay
Description: Collect Pay API will be used to raise collect request to the VPA present in the Payer
VA parameter in the request packet.
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/CollectPay3/{merchantId}
Live Endpoint:
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/CollectPay3/{merchantId}
Input Parameters:
Mandatory
Name Type Description (Y-Yes / O- Length
Optional)
merchantId Number Merchant Identification Y 10
Number
subMerchantId Number Sub Merchant Identification Y 10
Number of Merchant. If
there is no subMerchantId
required, merchant should
pass the same value as
‘merchantId’
terminalId Number Needs to send Merchant Y 4
category code (MCC code).
[Default MCC-5411]
merchantName String Name of the Merchant Y 50
subMerchantName String Sub Merchant Name of the Y 50
Merchant
payerVa AlphaNumeric Virtual Payment address of Y 255
the Payer
Amount Number Amount to be debited (In Y 20
Rupees) in Integer value
with 2 decimal
E.g. : ‘200.00’ or ‘300.12’
Note AlphaNumeric Remarks entered by the Y 50
payer for his reference.
collectByDate DATE TIME Format : dd/mm/yyyy Y
HH:MM AM/PM
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:
{
"payerVa": "testo@icici",
"amount": "5.00",
"note": "collect-pay-request",
"collectByDate": "08/11/2019 06:30 PM",
"merchantId": "118449",
"merchantName": "Testmerchant",
"subMerchantId": "118449",
"subMerchantName": "Test",
"terminalId": "5411",
"merchantTranId": "p0nillp0k9lqlp091p17",
"billNumber": "sdf1po111b",
"validatePayerAccFlag": "Y",
"payerAccount": "0405012740",
"payerIFSC": "ICI00012345",
}
Output Parameters:
{
"response":"92",
"merchantId":"118449",
"subMerchantId":"118449",
"terminalId":"5411",
"success":"true",
"message":"Transaction Initiated",
"merchantTranId":" p0nillp0k9lqlp091p17",
"BankRRN":"931013011368"
}
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)