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