HDFC Bank (UPI)

Merchant Integration Kit (Mobile App)

Prepared by

HDFC Bank, India

Version: 1.1

Private and Confidential Page 1

 Document Release Note

Project Name: UPI - Merchant Integration

Document Name HDFC Bank - Merchant Integration Document(Web)

Version: 1.1

Release Date:

Prepared by: Sunil Karkera Date: 25/09/2016

Reviewed by: Suresh K Date: 25/09/2016

Approved by: Vadivel S / Guhan Date: 26/09/2016

Document Revision History

V. No Revision Date Revision Description Release Date

1.0 - Initial Draft 25/09/2016

1.1 03/02/2017 NPCI 1.5 changes 03/02/2017

1.2 27/03/2017 Without Registration 27/03/2017

Private and Confidential Page 2

 Table of Contents
1. Introduction ...................................................................................................... 1
1.1 Purpose .................................................................................................................................. 1
1.2 Prerequisites .......................................................................................................................... 1
1.2 API List ................................................................................................................................... 1
1.3 Process Flow .......................................................................................................................... 1

2. API Integration .................................................................................................. 3

1.4 Transaction Service................................................................................................................ 3
1.5 Transaction Status Enquiry .................................................................................................... 9

3. Test URL .......................................................................................................... 13

4. Sample APK for Merchant App and HDFC BANK UPI UAT APP ........................... 13

5. HTML based Flow: ........................................................................................... 13

6. Merchant SDK Version 1.5 ............................................................................... 13

Private and Confidential Page 3

 1. Introduction

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. Also it describes the Client API functionalities
which provide quick integration effort solution for merchants. It is to include all the design and
implementation components for integration such as interfaces exposed by the API's to the end
systems, business and validation rules, transformation rules, data field mappings and
implementation logic.

1.2 Prerequisites
The merchant should have the following pre-requisites in place before integrating with BANK.

 Merchant has to be on boarded and receive Merchant ID

 Merchant Encryption Key which is sent to merchant on successful on boarding process.

 Merchant App should have permission to send Outward SMS

1.2 API List

BANK provides the following services to the merchant as part of this integration.

Sr No API Name Description

Transaction / Payment service Transaction Request API helps merchant
using which merchant can to initiate the PAY transaction through
1 initiate the Transaction Mobile App.

Customer can check for transaction status

2 Transaction Status Enquiry from the merchant app.

1.3 Process Flow

a Objective:

Process flow of a transaction through a Merchant App in UPI is explained in detail.

b Process Flow:

Private and Confidential Page 1

 c Functional Flow:

1 Customer uses a merchant app and while checking out after a purchase selects Pay by UPI as
the mode payment.

2 The Merchant app makes an intent call in the device and opens the banks App as the default
PSP App, and the customer also gets an option to choose any other PSP App.

Private and Confidential Page 2

 3 The bank App checks if the customer is registered with UPI or not with UPI.

4 If the customer is not registered with UPI then is directed to the registration page where the
customer has to create a Virtual Address and set MPIN and finish the transaction.

5 If the customer is registered then the customer is asked to enter MPIN, once the customer
inputs his/her MPIN then a debit request is send to the remitter bank and on the response is
sent back to NPCI.

6 NPCI passes the response to the PSP App after which the PSP App pushes the response to the
Merchant app.

7 The status of the transaction is displayed to the customer on the Merchant App.

2. API Integration

1.4 Transaction Service

Transaction Request API helps merchant to initiate the PAY transaction through Mobile App.

Request Parameters

Sr. Fields Description Data Type Length(Min- Mandator

No. Max) y /
Optional
1 MID Merchant ID Character 16 Mandatory

2 Merchant Key Merchant encryption Character 32 Mandatory

key
3 Merchant Trnx Unique Trnx reference Character 30 Mandatory
Reference(MerchantTx sent by merchant (Alpha
nID) Numeric)
4 Transaction Order summary Character 1100 Mandatory
Description description

5 Amount Transaction amount Number 16,2 Mandatory

6 Currency Transaction currency Character 5 Mandatory

Private and Confidential Page 3

7 APP Name(appid) Application Name Character 30 Mandatory

8 Payment Type P2P or P2M Character 5 Mandatory

9 Transaction Type Pay or Collect Character 10 Mandatory

10 Payee Payment Merchant Virtual Character 255 Mandatory

Address Address

11 Payee Account Remitter Account Character 18 Optional

Number Number

12 Payee IFSC Remitter IFSC Character 12 Optional

13 Payee Aadhaar Aadhaar Number 15 Optional

Number

14 Payee Mobile Mobile Number Number 12 Optional

Number

15 Payee Name Payee/Merchant Name Character 30 Mandatory

16 Merchant Category P2P – 4814, P2M – Character 10 Mandatory

Code1(mc) Relevant Codes
depending on
industry nature

Private and Confidential Page 4

17 Expiry Time Applicable only for Character 20 Optional
Collect Requests
(YYYY:MM:DD
HH:MM:SS)

18 Payer Account Remitter Account Character 18 Optional

Number Number

19 Payer IFSC Remitter IFSC Character 12 Optional

20 Payer Aadhaar Aadhaar Number Number 15 Optional

Number
21 Payer Mobile Number Mobile Number Number 12 Optional

22 Payer Payment Remitter Virtual Character 255 Optional

Address Address

23 Sub-Merchant ID Sub-Merchant ID Character 16 Optional

24 White listed Accounts Array of whitelisted Optional

accounts i.e. Bank
Name and account
numbers. Payer can
make payments only
from these account
numbers. To be
validated by SDK
(JSON Format)

25 Ref. URL Ref. URL Character 30 Optional

26 Payer MMID Payer MMID Number 7 Optional

27 Payee MMID Payee MMID Number 7 Optional

28 Additional Field 1 For future use Character 100 Optional

29 Additional Field 2 For future use Character 100 Optional

Allowed Merchant Category Codes (MCCs) will be made available as an annexure

Private and Confidential Page 5

30 Additional Field 3 For future use Character 100 Optional

31 Additional Field 4 For future use Character 100 Optional

32 Additional Field 5 For future use Character 100 Optional

33 Additional Field 6 For future use Character 100 Optional

34 Additional Field 7 For future use Character 100 Optional
35 Additional Field 8 For future use Character 100 Optional
36 Additional Field 9 For future use Character 100 NA
37 Additional Field 10 For future use Character 100 NA

Technical Integration Code:

Bundle bundle = new Bundle();

bundle.putString("mid", “BANK00000000001”);
bundle.putString("merchantKey", “fdc390bef3ef1ee3d4a7e77fd42238df”);
bundle.putString("merchantTxnID", “73643782”);
bundle.putString("transactionDesc", “Test Payment”);
bundle.putString("amount","1.00");
bundle.putString("currency", “INR”);
bundle.putString("appName", “com.merchant.package”);
bundle.putString("paymentType", “P2M”);
bundle.putString("transactionType", “PAY”);
bundle.putString("payeePayAddress", “”);
bundle.putString("payeeAccntNo", “”);
bundle.putString("payeeIFSC", “”);
bundle.putString("payeeAadhaarNo", “”);
bundle.putString("payeeMobileNo", “”);
bundle.putString("payeeName", “”);
bundle.putString("merchantCatCode", “1234”);
bundle.putString("expiryTime", “”);
bundle.putString("payerAccntNo", “”);
bundle.putString("payerIFSC", “”);
bundle.putString("payerAadhaarNo", “”);
bundle.putString("payerMobileNo", “”);
bundle.putString("payerPaymentAddress", “”);
bundle.putString("subMerchantID", “”);
bundle.putString("whitelistedAccnts", “”);
bundle.putString("payerMMID", "");
bundle.putString("payeeMMID", "");
bundle.putString("refurl", "");
bundle.putString("add1", add1);
bundle.putString("add2", add2);
bundle.putString("add3", add3);
bundle.putString("add4", add4);

Private and Confidential Page 6

 bundle.putString("add5", add5);
bundle.putString("add6", add6);
bundle.putString("add7", add7);
bundle.putString("add8", add8);
bundle.putString("add9", add9);
bundle.putString("add10", add10);

Intent intent = new Intent(getApplicationContext(), PayActivity.class);

intent.putExtras(bundle);
startActivityForResult(intent, 1);

Response Parameters

Sr. Fields Description Data Type Length Mandatory

No. / Optional
1 Transaction Unique Transaction Number 18 Mandatory
Reference No (Bank Reference Number
TxnID)
2 Merchant Transaction Unique order Character 30 Mandatory
Reference reference sent by
merchant
3 Amount Transaction Amount Number 16,2 Mandatory
4 Transaction Auth date Transaction date time Character 20 Mandatory
with timestamp
(YYYY:MM:DD
HH:MM:SS)
5 Status Transaction status Character 10 Mandatory
(Success, Failure, Time
out, Pending)

6 Status Description Transaction status Character 100 Mandatory

description
7 Response Code Transaction response Character 5 Mandatory
code

Private and Confidential Page 7

 8 Approval Number Transaction approval Character 30 Optional
number
9 Payer Virtual Address Virtual Address of the Character 255 Optional
buyer

11 NPCI UPI Transaction NPCI’s UPI ID Character 35 Mandatory

ID
12 Reference ID Reference ID as per Character 35 Optional
(TempRefID) NPCI’s requirement
13 Additional Field 1 For future use Character 100 Optional
14 Additional Field 2 For future use Character 100 Optional
15 Additional Field 3 For future use Character 100 Optional
16 Additional Field 4 For future use Character 100 Optional
17 Additional Field 5 For future use Character 100 Optional
18 Additional Field 6 For future use Character 100 Optional
19 Additional Field 7 For future use Character 100 Optional
20 Additional Field 8 For future use Character 100 Optional
21 Additional Field 9 For future use Character 100 NA
22 Additional Field 10 For future use Character 100 NA

Technical Integration Step:

protected void onActivityResult(int requestCode, int resultCode, Intent data)

{
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == 1 && resultCode == Activity.RESULT_OK
&& data != null)
{
Bundle bundle = data.getExtras();
String pgMeTrnRefNo = bundle.getString("pgMeTrnRefNo");
String orderNo = bundle.getString("orderNo");
String txnAmount = bundle.getString("txnAmount");
String tranAuthdate = bundle.getString("tranAuthdate");
String statusCode = bundle.getString("status");
String statusDesc = bundle.getString("statusDesc");
String responsecode = bundle.getString("responsecode");
String approvalCode = bundle.getString("approvalCode");
String payerVA = bundle.getString("payerVA");

Private and Confidential Page 8

 String npciTxnId = bundle.getString("npciTxnId");
String refId = bundle.getString("refId");
String add1 = bundle.getString("add1");
String add2 = bundle.getString("add2");
String add3 = bundle.getString("add3");
String add4 = bundle.getString("add4");
String add5 = bundle.getString("add5");
String add6 = bundle.getString("add6");
String add7 = bundle.getString("add7");
String add8 = bundle.getString("add8");
String add9 = bundle.getString("add9");
String add10 = bundle.getString("add10");
}
}

1.5 Transaction Status Enquiry

Transaction Status API facilitates the merchant to retrieve the transaction:

Request Parameters

Sr. Fields Description Data Type Length Mandatory /

No. Optional
1 MID Merchant ID Character 16 Mandatory
2 Merchant Key Merchant Encryption Character 32 Mandatory
Key
3 Merchant Transaction Unique order Character 32 Mandatory
Reference ID reference sent by
merchant
4 Bank UPI ID (Bank Bank BANK UPI Number 18 Optional
TxnID) Transaction ID
5 Reference ID Reference Id Character 35 Optional
6 Additional Field 1 For future use Character 100 Optional
7 Additional Field 2 For future use Character 100 Optional
8 Additional Field 3 For future use Character 100 Optional
9 Additional Field 4 For future use Character 100 Optional
10 Additional Field 5 For future use Character 100 Optional

Private and Confidential Page 9

 11 Additional Field 6 For future use Character 100 Optional
12 Additional Field 7 For future use Character 100 Optional
13 Additional Field 8 For future use Character 100 Optional
14 Additional Field 9 For future use Character 100 NA
15 Additional Field 10 For future use Character 100 NA

Bundle bundle = new Bundle();

bundle.putString("mid", “BANK00000000001”);
bundle.putString("merchantKey", “fdc390bef3ef1ee3d4a7e77fd42238df”);
bundle.putString("merchantTxnID", "9132012");
bundle.putString("bankTxnId", "");
bundle.putString("refranceId", “”);
bundle.putString("add1", “”);
bundle.putString("add2", “”);
bundle.putString("add3", “”);
bundle.putString("add4", “”);
bundle.putString("add5", “”);
bundle.putString("add6", “”);
bundle.putString("add7", “”);
bundle.putString("add8", “”);
bundle.putString("add9", “NA”);
bundle.putString("add10", “NA”);
Intent intent = new Intent(getApplicationContext(), TransactionStatus.class);
intent.putExtras(bundle);
startActivityForResult(intent, 3);

Response Parameters

Sr. Fields Description Data Type Length Mandatory

No. / Optional
1 Transaction Unique Transaction Number 18 Mandatory
Reference No Reference Number
(BankTxnID)
2 Merchant Transaction Unique order Character 30 Mandatory
Reference reference sent by
merchant
3 Amount Transaction Amount Number 16,2 Mandatory

Private and Confidential Page 10

 4 Transaction Auth date Transaction date Character 20 Mandatory
time with timestamp
(YYYY:MM:DD
HH:MM:SS)
5 Status Transaction status Character 10 Mandatory
(Success, Failure,
Pending, Time-out)

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)
9 Payer Virtual Address Virtual Address of the Character 255 Optional
buyer
11 NPCI UPI Transaction NPCI’s UPI ID Character 35 Mandatory
ID (NPCITxnID)
12 Reference ID Reference ID as per Character 35 Optional
(TempRefID) NPCI’s requirement
13 Additional Field 1 For future use Character 100 Optional
14 Additional Field 2 For future use Character 100 Optional
15 Additional Field 3 For future use Character 100 Optional
16 Additional Field 4 For future use Character 100 Optional
17 Additional Field 5 For future use Character 100 Optional
18 Additional Field 6 For future use Character 100 Optional
19 Additional Field 7 For future use Character 100 Optional
20 Additional Field 8 For future use Character 100 Optional
21 Additional Field 9 For future use Character 100 NA
22 Additional Field 10 For future use Character 100 NA

Private and Confidential Page 11

 protected void onActivityResult(int requestCode, int resultCode, Intent data)
{
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == 3 && resultCode == Activity.RESULT_OK
&& data != null)
{
Bundle bundle= data.getExtras();
String bankRegID = bundle.getString("bankRegID");
String merchantTxnID = bundle.getString("merchantTxnID");
String amount = bundle.getString("amount");
String txnAuthDate= bundle.getString("txnAuthDate");
String status = bundle.getString("status");
String statusdesc = bundle.getString("statusdesc");
String respCode = bundle.getString("respCode");
String approvalNo = bundle.getString("approvalNo");
String payerVA = bundle.getString("payerVA");
String npciTxnId = bundle.getString("npciTxnId");
String refranceId = bundle.getString("refranceId");
String add1 = bundle.getString("add1");
String add2 = bundle.getString("add2");
String add3 = bundle.getString("add3");
String add4 = bundle.getString("add4");
String add5 = bundle.getString("add5");
String add6 = bundle.getString("add6");
String add7 = bundle.getString("add7");
String add8 = bundle.getString("add8");
String add9 = bundle.getString("add9");
String add10 = bundle.getString("add10");
}
}

Private and Confidential Page 12

 3. Test URL
The below URL can be used by a merchant to test the connectivity.

https://upitest.hdfcbank.com

Connectivity can be checked by following ways:

1) Telnet – Should able to connect to Telnet.

2) OPENSSL – Install free SSL and by inputting the above URL the connection status should be
“Connected”.

3) Browsers – From browser the HDFC Sorry page should be displayed.

4. Sample APK for Merchant App and HDFC BANK UPI UAT APP
Download the sample Merchant APP from following link:

https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=HDFCMerchantV1.5.zi
p

Download the HDFC Bank UAT PSP APP following link:

https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=HDFC_PSP_UAT1.5.zip

5. HTML based Flow:

Download the HTML flow for Merchant & PSP from following link:

https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=PSP_Merchant_Screens_2016.
08.01.zip

6. Merchant SDK Version 1.5

Download SDK file for the merchant integration from following link:

https://upitest.hdfcbank.com/UploadAndDownload/download.jsp?fileName=Merchant_SDK_NPCI_1.5_wrg.
7z

Private and Confidential Page 13