API Documentation

EAZYPAY1.0

1
API Gateway-
Integration

2
Contents
Introduction..................................................................................................................... 4
API Details ....................................................................................................................... 5
1. API Name: QR API ...................................................................................................... 5
2. API Name: Transaction Status ...................................................................................... 8
3. API Name: Callback Status .........................................................................................10
4. API Name: Refund API ............................................................................................... 13
5. API Name: Collect Pay ............................................................................................... 15
6. Error Codes................................................................................................................18
Security...........................................................................................................................23
Encryption & Decryption Process ................................................................................... 24

3
Introduction:
 This document describes Merchant and ICICI Bank Integration through API Gateway for
Eazy-Pay Services.
 Customer journey, API specification and security implementation for Merchant integration.

4
 API Details

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
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/QR3/{merchantId}

PROD
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/QR3/{merchantId}

Method: POST

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

5
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.

6
 Sample Request
{
"amount": "5.00",
"merchantId": "118449",
"terminalId": "5411",
"merchantTranId": "p0nillp0k9lqlp091p17",
"billNumber": "sdf1po111b",
"validatePayerAccFlag": "Y",
"payerAccount": "0405012740",
"payerIFSC": "IC00000",
}

Output Parameters:

Name Type Description

merchantId Number Merchant Identification Number
terminalId Number Merchant category code
success Alphanumeric Result of the API Call
response String Response code indicating status of QR API
message String message description indicating status of QR
API
merchantTranId Alphanumeric This will be a Unique Transaction ID
generated by the Merchant.
refid Alphanumeric Reference id

Response Packet:

{
"response": "0",
"merchantId": "118449",
"terminalId": "5411",
"success": "true",
"message": "Transaction Initiated",
"merchantTranId": " p0nillp0k9lqlp091p17",
"refId":"EZY286844327832"
}

QR code generation string:

upi://pay?pa=<merchant VPA>&pn=<merchant name>&tr=<Refid>&am=<amount>&cu=INR&mc=<MCC code>

Example: upi://pay?pa=abc@icici&pn=Abc&tr=EZY123456789012&am=10&cu=INR&mc=5411

7
 2. 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
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/TransactionStatus3/{merchantId}

PROD
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/TransactionStatus3/{merchantId}

Method: POST

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 Request

{
"merchantId": "118449",
"subMerchantId": "118449",
"terminalId": "5411",
"merchantTranId": "p0nillp0k9lqlp091p17"
}

Output Parameters:

Name Type Description

Response Number Response Code
X` Number Merchant Identification Number
8
subMerchantId Number Sub Merchant Identification Number of
Merchant
terminalId Number MCC
Success String Result of the API Call
Message String Response Code Description

9
 merchantTranId AlphaNumeric This will be a Unique Transaction ID
generated by the Merchant.
OriginalBankRRN Number Reference Number generated by Bank
Amount Number Amount
Status AlphaNumeric Status of the transaction

Sample Response:

{
"response": "0",
"merchantId": "106161",
"subMerchantId": "12234",
"terminalId": "5411",
"OriginalBankRRN": "615519221396",
"merchantTranId": "612411454593",
"amount": "12",
"success": "true",
"message": "Transaction Successful",
"status": "SUCCESS"
}

3.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
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/CallbackStatus2/{merchantId}

PROD
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/CallbackStatus2/{merchantId}

Method: POST

Input Parameters:

Mandatory
Name Type Description Length
(Y/C)
merchantId Number Merchant Identification Y 10
Number

10
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

*Transaction Scenario MerchantT BankRRN RefId Transaction Date

Type Flag ranId
C Collect Pay Mandatory Non- N/A N/A
Transaction Mandatory
R Refund Mandatory Non- N/A N/A
Transactions Mandatory
Q ICICI generated Mandatory Non- Non- N/A
ref-Id (EZY or Mandatory Mandatory
EZP)
P Merchant Any 1 out Any 1 out of Any 1 out of Mandatory when
generated ref- of 3 3 3 search based on
Id or Push Ref Id

11
Sample Request

{
"merchantId": "118449",
"subMerchantId": "118449",
"terminalId": "5411",
"transactionType": "C",
"merchantTranId": "p0nillp0k9lqlp091p17"
}

Output Parameters:

Name Type Description

Response Number Response Code
merchantId Number Merchant Identification Number
subMerchantId Number Sub Merchant Identification Number of
Merchant
terminalId Number MCC
success String Result of the API Call
message String Response Code Description
merchantTranId AlphaNumeric This will be a Unique Transaction ID
generated by the Merchant.
OriginalBankRRN Number Reference Number generated by Bank
PayerVA AlphaNumeric Virtual Payment Address of the Payer
Amount Number Amount
status AlphaNumeric Status of the transaction
TxnInitDate Date and Time Date and time on which the transaction
was initiated
TxnCompletionDate Date and Time Date and time on which the transaction
was completed

Sample Response:

{
"response": "0",
"merchantId": "106161",
"subMerchantId": "12234",
"terminalId": "5411",
"OriginalBankRRN": "615519221396",
"merchantTranId": "612411454593",
"Amount": "12",
"payerVA": " testing1@imobile ",
"success": "true",
"message": "Transaction Successful",
12
 "status": "SUCCESS",
"TxnInitDate": "20160715142352",
"TxnCompletionDate": "20160715142352"
}

4.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
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/Refund/{merchantId}

PROD
https://apibankingone.icicibank.com/api/MerchantAPI/UPI/v0/Refund/{merchantId}

Method:POST

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

13
 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:

Name Type Description

Response Number Response Code
merchantId Number Merchant Identification Number
subMerchantId Number Sub Merchant Identification Number of
Merchant
terminalId Number MCC
success String Result of the API Call
message String Response Code Description
merchantTranId AlphaNumeric This will be a Unique Transaction ID
generated by the Merchant.
OriginalBankRRN Number Reference Number generated by Bank. For
Online refund, new RRN will be generated.
For Offline, Original RRN will be returned
status AlphaNumeric Status of the transaction

Sample Response

14
{
"merchantId": “106092”,
"subMerchantId": “12234”,
"terminalId": “2342342”,
"success": "true",
"response": “0”,
"status": "SUCCESS",
"message": "Transaction Successful",
"originalBankRRN": "622415338172",
"merchantTranId": "88442055"
}

5. 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
https://apibankingonesandbox.icicibank.com/api/MerchantAPI/UPI/v0/CollectPay3/{merchantId}

PROD
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]

15
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

16
 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:

Name Type Description

response Number Response Code
merchantId Number Merchant Identification Number
subMerchantId Number Sub Merchant Identification Number of
Merchant
terminalId Number Merchant category code
success String Result of the API Call
message String Response code Description
merchantTranId AlphaNumeric This will be a Unique Transaction ID
generated by the Merchant.
BankRRN Number Reference Number generated by Bank
17
Response Packet:
{
"response": "92",
"merchantId": "118449",
"subMerchantId": "118449",
"terminalId": "5411",
"success": "true",
"message": "Transaction Initiated",
"merchantTranId": " p0nillp0k9lqlp091p17",
"BankRRN": "931013011368"
}

Error Codes

Code Description Reasons

500 Internal Server Error Internal Server Error
401 Unauthorized APIkey,IP whitelisting or SSL not
present
403 Forbidden Request not proper.
429 Too Many Requests Too Many Requests
8002 INVALID_JSON. INVALID_JSON.
8003 INVALID_FIELD FORMAT OR Field is not in the format mentioned
LENGTH
8004 MISSING_REQUIRED_FIELD Mandatory field is missing
INVALID_FIELD_LENGTH Length of field exceeds defined
8006 length
8007 Invalid JSON, OPEN CURLY BRACE Open Brace missing in JSON
MISSING
8008 Invalid JSON,END CURLY BRACE Closing Brace missing in JSON
MISSING
8009 Internal Server Error White space characters
8010 INTERNAL_SERVICE_FAILURE The system had an internal
exception
8011 BACKEND_HOST_NOT_FOUND The Server referenced in the URL
cannot be reached.
18
8012 BACKEND_CONNECTION_TIMEOUT Cannot connect to service
8013 BACKEND_READ_TIMEOUT Cannot read from service
8014 BACKEND_BAD_URL The URL is incorrect.
8017 INVALID JSON Improper JSON
8016 Decryption Fail Request not properly Encrypted
5000 Invalid Request if the request is failed with some
other reasons
5001 Invalid Merchant ID If the merchant Id is not valid
5002 Duplicate Merchant TranId Transaction is already initiated with
merchant transaction id
5003 Merchant Transaction Id is If merchant transaction id null
mandatory
5004 Invalid Data invalid packet
5005 Collect By date should be greater If given collect by date is less than
than or equal to Current date current date
5006 Merchant TranId is not available No transaction initiated with given
transaction id based on merchant id

19
5007 Virtual address not present If merchant entered invalid
customer VPA
5008 PSP is not registered If merchant entered wrong PSP
handler
5009 Service unavailable. Please try later. Default error response for
unexpected internal failures.
5010 Technical Error If any technical error.
5011 Duplicate merchant TranId Transaction is already initiated with
merchant transaction id
5012 Request has already been initiated If request is initiated already for this
for this transaction transaction.
5013 Invalid VPA If VPA does not exits
5014 Insufficient amount If Original amount is less than
refund amount
5015 Invalid Original TranId If original transaction Id is not
available
5016 Payee VA should not be Merchant Should not be Merchant Virtual
VA Address
5017 Sorry you can't initiate refund Merchant can initiate online refund
request only if online refund flag is enabled
5018 Merchant VPA and Reference ID is
not match
5019 Invalid Terminal Id
5020 No response from Beneficiary Bank. For Deemed approved transactions
Please wait for recon before or timed out requests
initiating the transaction again.
5021 Transaction Timed out. Please check OSB Timed out for collect request
transaction status before initiating
again.
5022 Terminal Id is mandatory
5023 Multiple transactions against given
parameter. Please provide bank RRN
5024 Record not found against given
parameters
5025 Please enter valid refund amount
5026 Invalid Consumer number
5027 Invalid merchant prefix
5028 Virtual Address Already Exists
5029 No Response From Switch

20
5030 Please try again In case Check VPA return actCode
950 from Switch
5031 Validity start date should not be less If Validity start date is less than
than current date current date

21
5032 Validity end date should not be less If Validity end date is less than
than validity start date validity start date
5033 Mandate request not created Without initiating the manage
mandate
5034 No Approved Mandates are available If manage mandate request are not
in SUCCESS state
5035 Mandate expired If mandate validity period is
completed
5036 Mandate amounts mis-matched If manage mandate is EXACT and
different amount given in execute
mandate
5037 Execution amount exceeded to If manage mandate is MAX and
Mandate approved amount execution amount crossed in
execute mandate
5038 Invalid Validate Payer Account Flag If validate payer account flag is
other than Y and N
5039 Invalid Payer Account If Payer Account is null, empty or
invalid pattern
5040 Invalid Payer IFSC If Payer IFSC is null, empty or invalid
pattern
5041 Invalid Sequence Number
5042 Duplicate Sequence Number
5043 Invalid Unique Merchant ReferenceId
5044 Invalid Merchant Name
5045 Invalid Marketing Name
5046 Invalid Bank Assigned MerchantId
5047 OSB Timeout
5048 New Unique Merchant ReferenceId
5049 Failed at switch. Please try
registering again.
5050 Details of Bank Assigned MerchantId
not found
5051 Duplicate Unique Merchant
ReferenceId

22
Security

a. API Key needs to be passed in every request in the header and merchant IPwill
also be required for IP whitelisting.
b. API Key needs to be passed in the parameter name: apikey
c. API request and response to Merchant is secured using advanced and agreed
upon encryption algorithm agreed to maintain data confidentialityand integrity.
d. 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.

23
Encryption & Decryption Process

Asymmetric Encryption & Decryption Process Payload content-type will be in text/plain. Base64 encoded
encrypted Cipher will be passed as a payload.

oG5mU1JJNBuwQaSLKb3wfRZks/cT2Vo2yBNNuqjNHDWEC144WxC8iKqBpJAgq7reFKC4sHNUmNPRD
ya1AvmQ7x1L+3EAdEs9FEWNurZuWTvZpk4y7JrGhg0rz9KptBf+JfJUkSMo7NR3Saxel6EYtckkDr3AG
W7WJZmhcEoAMMXRws/hLVmaNHC/nOjCNqqBd4IOOAzdJh/HADRVI+YAJKT8dE4x9NTl+UX1zAoo
Whza+TsWEHfxzQIa7zai7WSa/wiJD3uD7mk5vT1WY/fKJBquCuzM7l35vigDhmb7dLVLuX8VMiNQrtErW
NI0uVaag1jg+uZUtyDSxjPFi5yEpKVVc7+T503IDnCvkCFDygqasDsPL24qOjYk4XavTZvwGuPAdYNNkVn
LzVElEhg4zS2ye+fa/8fZiMt/3fwYeN9dgn9i5R6VOFbXSuZJYPSci9k0oqz73h1nzFtps60rUEDoGIkGvm9w
aJU3W78VH5mIdGfGvvJjiKIuVHmi/huzEX9v4w3mW7RDGgmOuKImkqki+XWgyB0JvVmsLdO+cBaym/
seZP3+zdfhO9AWSI2tDLD4Vf0jDjzoDSFN2mzUFgHK9mbtbXgvsnReoGqx/KsivzmZNLmDmtg8eR4Z9Ln
Lni4rl4OtkDv5y/mxMtL3MBUUUajkw6OS6NnhEG895yo

For encryption of request at ICICI:

Encrypted_Payload = Base64Encode(RSA/ECB/PKCS1Encryption(payload,ICICIPubKey.cer))

For encryption of response at ICICI:

Encrypted_Payload = Base64Encode(RSA/ECB/PKCS1Encryption(payload,ClientPubKey.cer))

For decryption of response at Client:

plainResponse = Base64Decode(RSA/ECB/PKCS1Decryption(encPayload,ClientPrivateKey.p12))

24