Professional Documents
Culture Documents
UPI-Merchant Integration Kit Web V1.4
UPI-Merchant Integration Kit Web V1.4
Prepared by
Version: 1.4
1.1 Purpose
The purpose of this document is to detail out the technical integration approach for web
based integration between UPI platform and merchants. This document describes the
process flow and Client API functionalities which provide quick integration for merchants.
This document is complimented with the toolkit for merchant integration in the UPI platform.
Note: This Merchant Integration document is intended for Merchants that are available only on
the web (Website) for the customers to make payments to the merchant and wants to collect
near real time.
3. Customer: Existing UPI customer with a virtual address with any of the PSP.
Customer approves the transaction through the mobile app provided by the PSP.
a Objective:
Process flow of a transaction through a Web based merchant in UPI is explained in detail.
c Functional Description:
1. Customer goes to the merchant website and while checking out after a purchase
selects "Pay by UPI" as the mode payment thereby inputting his/her Virtual
address (for eg : customername@bankname).
2. A collect request is initiated by the merchant and is sent to the Bank UPI server from
the Merchant web server, along with a defined expiry time for the request.
3. Bank UPI Server passes the request to NPCI, and NPCI passes the request to the
remitter bank.
4. Once the remitter bank validates the Virtual address and his/her account
details the request is pushed to the customers PSP App as a notification in the
Inbox.
5. The customer gets an option to accept or reject the request from the PSP APP
and the respective response is passed on to the remitter bank.
3 API List
UPI platform provides the following API to the merchant
Check VPA
Check VPA API helps merchant to check if the provided VPA is valid or invalid.
Request Parameters
No.
1 PG Merchant Id Merchant ID Character 16 Optional
Mandatory
2 Merchant Ref No Unique order Character 30 Mandatory
reference sent by
merchant
3 Payer Virtual Address Payer Virtual Address Character 255 Mandatory
4 Status Transaction Status (T) Character 2 Mandatory
5 Additional Field 1 For future use Character 100 Optional
6 Additional Field 2 For future use Character 100 Optional
7 Additional Field 3 For future use Character 100 Optional
8 Additional Field 4 For future use Character 100 Optional
9 Additional Field 5 For future use Character 100 Optional
10 Additional Field 6 For future use Character 100 Optional
11 Additional Field 7 For future use Character 100 Optional
12 Additional Field 8 For future use Character 100 Optional
13 Additional Field 9 For future use Character 100 NA
14 Additional Field 10 For future use Character 100 NA
UPI000000000086|20160728111155|kuldip30@hdbcbank|T|||||||||NA|NA
Response Parameters
1
No. Merchant Ref No Unique order Character 30 /Mandatory
Optional
reference sent by
merchant
2 Payer Virtual Address Payer Virtual Address Character 255 Mandatory
3 Payer Name Payer Account Name Character 50 Mandatory
4 Status Status Character 20 Mandatory
(VE=Available,
VN=Not Available,
F=Failed)
20160728111155|kuldip30@hdbcbank|Kuldip D|VE|VE|||||||||NA|NA
Collect Transaction Request API helps merchant to integrate with UPI platform for
initiating collect payment request to their customers.
Request Parameter
No. / Optional
1 PG Merchant Id Merchant ID Character 16 Mandatory
reference sent by
merchant
3 Payer Virtual Address Payer Virtual Character 255 Mandatory
Address
Amount in rupees
5 Remarks Order summary Character 1-50 Mandatory
6 Expiry value Expiry value in Number 10 Mandatory
minutes
7 MCC Code Merchant Category Number 04 Mandatory
Code
8 Additional Field 1 For future use Character 100 Optional
9 Additional Field 2 For future use Character 100 Optional
10 Additional Field 3 For future use Character 100 Optional
11 Additional Field 4 For future use Character 100 Optional
12 Additional Field 5 For future use Character 100 Optional
13 Additional Field 6 Merchant Request Character 100 Optional
Type : MEBR (On
sending MEBR in
this field there will
be validation of
account number
which will be sent in
additional field 7. If
blank is sent then
there will be no
validation of
account number)
(Customer Account
number available at
merchant end will
be sent in this field.
It is separated by
“!”. Maximum 4
account number can
only be sent)
15 Additional Field 8 For future use Character 100 Optional
16 Additional Field 9 For future use Character 100 NA
17 Additional Field 10 For future use Character 100 NA
PGMerchantId|OrderNo|PayerVA|Amount|Remarks|expValue|
MCC Code|1|2|3|4|5|6|7|8|NA|NA = 17 Nos.
UPI000000000001|12345|pankaj@bank|510|TEST|10|6012|||||||||NA|NA
No.
1 Order No. Unique order Character 30 / Optional
Mandatory
reference sent by
merchant
Private & Confidential 10 | P a g e
2 UPI Transaction Unique UPI Transaction Number 18 Mandatory
Reference ID Reference
(SUCCESS, FAILED)
VA|1|2|3|4|5|6|7|8|NA|NA = 17 Nos
|pankaj@bank|merchant@bank|||||||||NA|NA
Transaction Status Enquiry API helps merchant to fetch the transaction status from UPI
engine by passing transaction reference no.
Request Parameters
1
No. PG Merchant Id Merchant ID Character 16 Mandatory
Optional
2 Order No Unique order Character 30 Mandatory
reference sent by
merchant
UPI000000000086|20160728111155|65437829217889||||||||||NA|NA
Response Parameters
1
No. UPI Transaction Unique UPI Number 18 Mandatory
/ Optional
Reference ID Transaction ID
(SUCCESS, FAILED,
PENDING, EXPIRED,
REJECTED & SPAM)
6 Status Description Transaction status Character 100 Mandatory
description
7 Response Code Transaction response Character 5 Mandatory
code
8 Approval Number Transaction approval Character 30 Optional
number (Core bank
ref number)
12 ID)
Additional Field 1 For future use Character 100 Optional
|2|3|4|5|6|7|8|9|NA|NA = 21 Nos
76786876876|20160728111155|100.00|2016:07:28
09:32:54|SUCCESS|Transaction Success|00|||UPI38A1AF0B2B2B601CE05500000000000
||||||||||NA|NA
Call back URL API helps merchant to receive the transaction status from the bank UPI server.
Response Parameters
1
No. UPI Txn ID Unique UPI Number 18 Mandatory
/ Optional
Transaction ID
UPI000000000021|123480001|1000104869|18211|632914904780|Order
Refund|10.00|INR|P2P|PAY|||||||||NA|NA
1
No. UPI Txn ID Unique UPI Number 18 Mandatory
/ Optional
Transaction ID
25519|123480001|10.00|2016:12:12 05:38:21|S|Transaction
Success|00|NA|rajesh@hdfcbank|634717906803|NA|NA|NA|NA|NA|NA|NA|NA|N
A| NA|NA
This merchant key will be shared by the bank and the merchant has to use the key
to encrypt/decrypt the message.
1. Merchant builds the request message (in pipe separated) and encrypts it
with merchant key.
Json format:
{"requestMsg":"1AD4F41171F0EA0C24A91CA5FA5807CD8704BAF9BA2DBBBF681F2
21240E92CF1A2DA364516E964C2221C54AF2E703BF06131916DB00CA032FD74B15
902995F07EF7B1FDDD6DADBEA205846926D7DAFBB6996821DAAF01122932F25
5C
C70DB4B8FEBFCD188F7316B7997A4B3695BB45C041228D458BFE7AF6014168A9
32
String encMsg =
security.encrypt("UPI0000000000001|1476439805968867|kuldip11@hdfcbank|100
|Test
Transaction|10|0000|||||||||null|null","easd343dsdsdsdsde3243dfffdeerfff");
String resMsg
=security.decrypt("1AD4F41171F0EA0C24A91CA5FA5807CD8704BAF9BA2DBBBF681
F221240E92CF1A2DA364516E964C2221C54AF2E703BF06131916DB00CA032FD74B
15F902995F07EF7B1FDDD6DADBEA205846926D7DAFBB6996821DAAF01122932F2
55CC70DB4B8FEBFCD188F7316B7997A4B3695BB45C041228D458BFE7AF6014168A
93278BB3", "easd343dsdsdsdsde3243dfffdeerfff");
7 Test URL
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=HDFCMerchantV1.5.zip
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=HDFC_PSP_UAT_1.5.zip
Note:- Please Download HDFC Bank PSP Production APP from Playstore.
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=HDFC_WebDemo.zip
10 UPI me Toolkit-1.0
Below is the inserted Jar file link for the merchant integration:
JAVA
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=upimetoolkit-1.0 .jar
Dot Net
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=Enc_Dnc_DLL.zip
PHP
https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=UPI_Merchant_Tool_K
it_PHP.zip
175.100.160.57
175.100.160.58
175.100.160.62
175.100.160.70
175.100.161.32
175.100.161.31
175.100.162.154
175.100.162.155
175.100.162.162
175.100.162.200