ICICI BANK UPI API
Onboarding manual
V1.8
ICICI Bank API Management Suite
MERCHANT ON BOARDING PROCESS
Merchant needs to provide the following information for onboarding:
Organization Name
Contact First Name
Contact Last Name
Contact Email Address
Calling server IPs (UAT & Production) and port
Account Number for credit
IFSC Code for credit
Expected Volume , TPD, TPS
Merchant call-back URL
Public key of merchant’s SSL certificate
Bank will provide ICICI bank’s public key of SSL certificate. Merchant will need to make REST call to APIs f rom its
Application Server, the IP of which needs to be whitelisted.
TRANSACTION API
API format
The URL to be used is: https:// api.icicibank.com:8443/<apiName>
The specific name of different APIs is mentioned in the below sections. The customer parameters to be passed
are, again, specific to each API. Below is the format for sending details. 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:
Base64Encode(RSA_Encrypt( { "merchantId" : "111111", "subMerchantId" : "12234", "terminalId" : "2342342",
"merchantTranId" : "612413726581",…,… }))
Encryption needs to be done using RSA 4,096 bits using the key provided by ICICI Bank.
ICICI Bank API Management Suite
Collect Pay API Request Call
The URL is https:// api.icicibank.com:8443/collectPay
The UAT URL of the same is https://apigwuat.icicibank.com:8443/newCollectPay
For collectPay API Request Call, the following parameters and their values need to be passed in encrypted
message:
payerVa , amount, note, collectByDate (format: DD/MM/YYYY HH:MM AM/PM), merchantId,
subMerchantId, terminalId, merchantTranId, billNumber
The details of the parameter values:
Field Remarks Type Length
merchantId Merchant ID given by ICICI Bank at the time of on- Numeric 10
boarding
merchantName Name of the merchant Alphanumeric 50
subMerchantId Sub-merchant ID in case Merchant is an aggregator Numeric 10
(Optional)
subMerchantName Name of the sub-Merchant (Optional) Alphanumeric 50
terminalId Needs to send Merchant category code (MCC Numeric 4
code). It should be 4 digit number. [UAT MCC-
5411]
merchantTranId Transaction reference ID of the merchant Alphanumeric 20
ICICI Bank API Management Suite
billNumber Optional field to add a bill number apart from the Alphanumeric 50
transaction ID
payerVa Payer’s virtual payment address communicated to Alphanumeric 255
the merchant
amount Amount of the transaction Numeric with 20
two decimal
point
note Optional remarks field Alphanumeric 50
collectByDate If the collect from payer is delayed collect, fill this Date and Time
field with the date and time by which the payer
needs to authorize the payment. This date cannot (DD/MM/YYYY
HH:MM
be a past date
AM/PM)
Note: For UAT purpose, please send values in optional parameters also. Values can be static values.
Sample: CollectPay Request
{
"payerVa" : "vishal2@icici",
"amount" : "5.00",
"note" : "collect-pay-request",
"collectByDate" :"30/12/2016 06:30 PM",
"merchantId" : "106088",
"subMerchantId" : "12234",
"terminalId" : "5411",
"merchantTranId" : "ABCD290806",
"billNumber" : "sdf234234"
}
ICICI Bank API Management Suite
Response to the Collect pay request
The API will send below parameters in the immediate response to the collect pay request. Response will be
encrypted with merchant’s public key shared with ICICI bank. Merchant needs to decrypt the response with their
own the private key of the key pair shared with ICICI Bank.
Field Remarks
response Response code indicating the status of CollectPay request
merchantId Merchant ID given by ICICI Bank at the time of on-boarding
subMerchantId Sub-merchant ID in case Merchant is an aggregator (Optional)
terminalId To identify specific entities within the sub-merchant (if applicable)
Success Indicates the status of this transaction
Message Message indicating status of the CollectPay request transaction
merchantTranId Transaction reference ID of the merchant
BankRRN Transaction reference number of ICICI Bank
Sample:
{
"response": "92",
"merchantId": "106088",
"subMerchantId": "12234",
ICICI Bank API Management Suite
"terminalId": "5411",
"success": "true",
"message": "Transaction initiated",
"merchantTranId": "0030011111101",
"BankRRN": "628610627304"
}
Response Codes of Response to collect pay Request
Response Code Success Message
92 Transaction Initiated
1 User profile not found
4 Response parsing error
9 Transaction rejected
10 Insufficient data
5000 Invalid Request
5001 Invalid Merchant ID
5002 Duplicate MerchantTranId
5003 Merchant Transaction Id is mandatory
5004 Invalid Data
5005 Collect By date should be greater than or equal to Current date
5006 Merchant TranId is not available
5007 Virtual address not present
5008 PSP is not registered
5009 Service unavailable. Please try later.
All other values of response
Transaction has failed
code
ICICI Bank API Management Suite
Transaction Status Check Call
The URL is https:// api.icicibank.com:8443/transactionStatus
The UAT URL for this is: https://apigwuat.icicibank.com:8443/newTransactionStatus
For transactionStatus request Call, the following parameters and their values need to be passed in encrypted
message:
merchantId, subMerchantId, terminalId, merchantTranId
Field Remarks Type Length
merchantId Merchant ID given by ICICI Bank at the time of Numeric 10
on-boarding
subMerchantId Sub-merchant ID in case Merchant is an Numeric 10
aggregator
terminalId Merchant category code(MCC) for auto Numeric 4
charging module based on category of
merchant
merchantTranId Transaction reference ID of the merchant Alphanumeric 20
Sample:
Transaction Status
{
"merchantId": "106092",
"merchantTranId": "6CnKxKtuhVYNDe",
"subMerchantId": "1000000000",
"terminalId": "5411"
}
ICICI Bank API Management Suite
ICICI Bank API Management Suite
Response to the Transaction status check
The API will send below parameters in the immediate response to the collect pay request. Response will be
encrypted with merchant’s public key shared with ICICI bank. Merchant needs to decrypt the response with their
own the private key of the key pair shared with ICICI Bank.
Field Remarks
Response Response code indicating the status of the transaction status check
merchantId Merchant ID given by ICICI Bank at the time of on-boarding
subMerchantId Sub-merchant ID in case Merchant is an aggregator (Optional)
terminalId Merchant category code(MCC) for auto charging module based on
category of merchant
Success Indicates the status of the transaction status check request. If “true”,
the status check transaction is successful
Message Status of the transaction status check
merchantTranId Transaction ID of the merchant as sent in the request from the
merchant
OriginalBankRRN Transaction reference number of ICICI Bank of the original transaction
Status Indicates the status of the original transaction that is being queried
ICICI Bank API Management Suite
Sample:
{
"response": "0",
"merchantId": "106088",
"subMerchantId": "1000000000",
"terminalId": "5411",
"success": "true",
"message": "Transaction Successful",
"merchantTranId": "0030011111101",
"OriginalBankRRN": "628610627304",
"status": "PENDING"
}
Current response
PENDING, SUCCESSS, FAILURE
ICICI Bank API Management Suite
Response on the Call Back URL
Field Remarks Type Length
merchantId Merchant ID given by ICICI Bank at the time Numeric 10
of on-boarding
subMerchantId Sub-merchant ID in case Merchant is an Numeric 10
aggregator (Optional)
terminalId To identify specific entities within the sub- Numeric 10
merchant (if applicable)
PayerName Name of the Payer Alphanumeric 50
PayerMobile Mobile number of the Payer Numeric 10
PayerVA Virtual Payment Address of the Payer Alphanumeric 255
PayerAmount Amount of the transaction Numeric 20
TxnStatus Status of the transaction
TxnInitDate Date and Time on which the transaction Date and Time
was initiated
(YYYYMMDDHHMMSS)
TxnCompletionDate Date and Time on which the transaction Date and Time
was completed
ICICI Bank API Management Suite
(YYYYMMDDHHMMSS)
BankRRN Bank reference number for this transaction Alphanumeric 50
Sample
"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"
Current expected TxnStatus
SUCCESS,
REJECTED (For all scenarios)
ICICI Bank API Management Suite
