Strictly Private and Confidential

Technical
Specification
Document
UPI - Linking
Specifications v13.0

Strictly Private and Confidential

Strictly Private and Confidential

STATEMENT OF CONFIDENTIALITY AND DISCLAIMER
The contents presented in this document are strictly confidential and proprietary to NPCI
International Payments Limited (“NIPL”) and/or its affiliates. This document is intended
solely for the recipient’s internal use and for evaluating the proposed transaction or
arrangement with NIPL and does not constitute, nor should it be construed as, an offer,
invitation, commitment or recommendation.
This document does not support a complete description of the subject matter referred
to herein. While the utmost care has been taken in preparing this document, NIPL and/or
its affiliates claim no responsibility and make no representation, warranty (whether
express or implied) for the accuracy, adequacy, reliability or completeness of the
information contained herein. All the information contained in this document is provided
on an “as is” basis, without any warranty of merchantability, fitness for a particular
purpose or non-infringement.
All intellectual property rights in and to this document, including without limitation in its
contents, design, structure, specifications, underlying know-how, and all related
material therein, shall remain with NIPL and/or its affiliates, and no license or other rights
(whether express or implied) are granted to the recipient except as provided under this
document.
The recipient shall not modify, alter, reproduce, distribute, publish, transmit, disclose,
display, create derivative works of, or otherwise exploit this document, in whole or in
part, without the prior written consent of NIPL. Any unauthorized use, disclosure or
public dissemination of information contained herein is prohibited.
Unless otherwise expressly agreed in writing, NIPL and/or its affiliates shall not be
responsible for any reliance placed on the contents of this document, and the recipient
shall use and evaluate the information contained herein at its own discretion and risk. To
the fullest extent permitted by applicable law, NIPL and/or its affiliates shall not be liable
for any direct, indirect, incidental, consequential, or special loss or damage arising from
the use of, reliance on, or inability to use this document.
Any suggestions, comments, feedback, enhancement requests, recommendations, or
other inputs voluntarily provided by the recipient relating to this document may be freely
used, adopted, modified, incorporated, disclosed, and otherwise exploited by NIPL
and/or its affiliates without restriction and without any obligation of attribution,
confidentiality, royalty, or compensation to the recipient.
The information and contents shared in this document are subject to change at any time
without notice. NIPL and/or its affiliates undertakes no obligation to update or revise the
same.
© NIPL 2026, All rights reserved.

Strictly Private and Confidential

VERSION CONTROL SUMMARY
Version

Created by

Released
Date

Reviewed by

Remarks

Version 13 Dhruvi Monga,
Meruva
Kusuma

10/08/2026 Gaurav Lodha, Comprehensively
Rishu Sinha
revised the TSD with the
addition of Error Codes,
a revamped document
structure, updated API
specification tables,
and refined language to
enhance readability and
usability.

Version 12 Dhruvi Monga

28/03/2023 -

Invoice tag updated.

Version 11 -

28/03/2023 -

Merchant tags, sign
updated.

Version 10 -

28/03/2023 -

Merchant tags updated
w.r.t. compliance
circulars. Parameter
definition table updated
for description.

Strictly Private and Confidential

Contents
1.

INTRODUCTION .............................................................................................. 2
1.1
1.2

2.

SAMPLE USE CASES ........................................................................................ 3
2.1
2.2
2.3
2.4

3.

Purpose ............................................................................................... 2
Scope .................................................................................................. 2

Offline UPI Acceptance - QR Based Payments......................................... 3
Online UPI Acceptance - QR Based Payments ......................................... 4
Offline UPI Reverse Acceptance - QR Based Payments ............................ 4
Online UPI Acceptance - In-App Payments.............................................. 5

LINK SPECIFICATION AND PARAMETERS........................................................... 6
3.1
3.2
3.3
3.4

Creation ............................................................................................... 6
Signature ............................................................................................ 19
Verifying The Intent:............................................................................. 22
Actions:.............................................................................................. 23

4.

NOTE ............................................................................................................ 23

5.

RESPONSE PARAMETRES ............................................................................... 24

6.

IMPLEMENTATION SAMPLES .......................................................................... 25
6.1
6.2
6.3

7.

Hyperlink (Intent URL) ......................................................................... 25
QR Code............................................................................................. 26
Others ................................................................................................ 30

APPENDIX ..................................................................................................... 31

Strictly Private and Confidential

TABLE OF ABBREVIATIONS
Foreign Currency

FCY

Forex

FX

International Partner

IP

NPCI International Payments Limited

NIPL

National Payments Corporation of India

NPCI

Payment Service Provider

PSP

Person-to-Merchant

P2M

Person-to-Person

P2P

Point of Sale

PoS

Software Development Kit

SDK

Unified Payment Interface

UPI

1

Strictly Private and Confidential

1. INTRODUCTION
Unified Payments Interface (UPI) is a real-time digital payment system, developed by the
National Payments Corporation of India (NPCI), that facilitates interbank Person-toMerchant (P2M) and Person-to-Person (P2P) transfer of money.
Along with domestic payments, UPI also supports foreign remittances and international
merchant payments. The latter, known as Global UPI Acceptance, enables Indian users
travelling overseas to make seamless payments at international merchants using their
UPI apps.
International UPI transactions can be initiated through multiple methods, such as:
1. In-app payments, where the international merchant’s application and mobile
browser send a payment request to the UPI application on the same device.
2. QR code-based payments, where users scan UPI-enabled QR code at an international
merchant outlet or at an international e-commerce platform using their UPI-enabled
application.

1.1 PURPOSE
This document defines the technical specifications and guidelines for enabling
international transactions using UPI, including cross-border P2M payments. It helps
developers and ecosystem partners implement secure, compliant, and interoperable
solutions for Global UPI Acceptance across in-app and QR-based payment flows.

1.2 SCOPE
This document covers the technical specifications for enabling international UPI
transactions using UPI links, QR codes, and intent-based payment flows. It includes:
1. Creation and processing of UPI URLs for international use cases with support for
payment initiation via QR codes (static/dynamic) and in-app intent flows.
2. Definition and usage of mandatory, optional, and conditional parameters for
transaction processing.
3. Guidelines for merchant integration, including link generation, QR creation, and
payment.
4. Security requirements such as signing and signature verification.
5. Interoperability requirements across Payment Service Provider (PSP) apps,
merchants, and (International Partners) Ips.

2

Strictly Private and Confidential

2. SAMPLE USE CASES
2.1 OFFLINE UPI ACCEPTANCE - QR BASED PAYMENTS
Example 1: International payment at merchant’s location using dynamic QR.
Case study: Priya is on a one-month trip to a foreign country and is standing at a grocery
store to pay for her purchases.
1. Priya asks the vendor to initiate the payment through UPI.
2. She uses her bank provided UPI application installed on her smartphone to scan the
dynamic QR code generated by the international grocery Point of Sale (PoS)
application.
3. The dynamic QR carries information about the merchant and the transaction amount.
4. The UPI application takes her straight to the pay screen with all values pre-populated
from the QR.
5. The UPI application displays information containing Foreign Currency (FCY), Forex
(FX) rate, and payable INR value to Priya.
6. She verifies the information and authorises the payment by entering her UPI PIN.
7. Both the merchant and Priya receive payment confirmation instantly.
Example 2: International payment at merchant’s location using static QR of the
international merchant.
Case study: Dev is on vacation in a foreign country and wants to make payment for
souvenirs that he has purchased at a gift shop.
1. Dev is exploring the local markets in a foreign country on the last day of his trip. He
notices the decal of UPI at a local gift shop which has been acquired by the IP.
2. He picks the souvenir and scans the static QR of the international merchant through
his UPI application.
3. On scanning the QR, the application shows him the merchant’s details and prompts
him to enter the amount in FCY.
4. Dev verifies the details shown on the application with the merchant.
5. He enters the FCY amount. The UPI application displays information containing FCY,
FX rate, and payable INR value.
6. Dev verifies the information and authorises the payment by entering his UPI PIN.
7. Both the merchant and Dev receive the payment confirmation instantly.

3

Strictly Private and Confidential

2.2 ONLINE UPI ACCEPTANCE - QR BASED PAYMENTS
Example 1: Payment to the international merchant via e-commerce site using dynamic
QR.
Case study: Neha is buying international goods/services online and needs to make an
online payment on an international e-commerce website.
1. Neha browses an international e-commerce website and adds items to the cart. At
checkout, she selects UPI as the payment method.
2. The dynamic QR code is generated and displayed, which carries information about
the merchant and the transaction amount.
3. She uses the UPI enabled application installed on her smartphone to scan the
generated dynamic QR code.
4. The UPI application displays information containing FCY, FX rate, and payable INR
value to Neha.
5. She verifies the information and authorises the payment by entering her UPI PIN.
6. Both the merchant and Neha receive payment confirmation instantly.

2.3 OFFLINE UPI REVERSE ACCEPTANCE - QR BASED PAYMENTS
Example 1: International customer paying an Indian merchant by scanning dynamic UPI
QR.
Case study: Mary is on a 1-month visit to India and is picking up souvenirs to take back
home. After she has selected the goods, she is ready to pay the merchant for her
purchases.
1. Mary asks the vendor to initiate the payment through UPI.
2. She uses IP provided UPI application installed on her smartphone to scan the
dynamic QR code generated by the Indian merchant’s PoS application.
3. The dynamic QR carries information about the merchant and the transaction amount.
4. The UPI application redirects her to the payment screen with all values pre-populated
from the QR.
5. The UPI application displays information containing INR amount, FX rate, and payable
FCY amount to Mary.
6. Mary verifies the information and authorises the payment.
7. Both the merchant and Mary receive transaction confirmation instantly.

4

Strictly Private and Confidential

Example 2: International customer paying Indian merchant by scanning static UPI QR.
Case study: Antony is exploring the local markets in India on the last day of his trip. He
notices the decal of UPI at a local gift shop.
1. Antony picks the souvenir and scans the static QR placed at the Indian merchant’s
payment desk through his UPI enabled IP application.
2. On scanning the QR, the application shows him the details of the merchant and
prompts him to enter the amount in INR.
3. Antony verifies the details and enters the INR amount following which the UPI
supported IP mobile application displays information containing INR amount, FX rate,
and payable FCY amount.
4. Antony verifies the information and authorises the payment.
5. Both the merchant and Antony receive transaction confirmation instantly.

2.4 ONLINE UPI ACCEPTANCE - IN-APP PAYMENTS
Example 1: International payment for goods purchased through the international
merchant’s mobile app using intent URL.
1. Hari browses an international merchant’s mobile app and adds items to his cart. At
checkout, he selects UPI as the payment method.
2. The intent URL is generated which carries information about the merchant and the
transaction amount.
a. For iOS device: UPI-enabled applications are listed on the merchant’s app,
allowing customers to choose their preferred app for payment. Once selected, an
intent URL is generated specifically for that app, and the customer is redirected
to the app to complete the transaction.
b. For Android device: A common intent URL is generated and all UPI enabled apps
installed in the device will be invoked. The customer selects the preferred UPI
application to complete the payment.
3. Hari is redirected to the selected UPI application which displays information
containing FCY, FX rate, and payable INR value.
4. Hari verifies the information and authorises the payment by entering his UPI PIN.
5. Both the merchant and Hari receive transaction confirmation instantly.

5

Strictly Private and Confidential

3. LINK SPECIFICATION AND PARAMETERS
UPI URL specifications must be as follows - all UPI applications must mandatorily
implement considering “UPI” links within their mobile applications for QR and intent.

3.1 CREATION
Following are the UPI supported formats for the creation of UPI URL:
1. Signed QR/intent: Normal signed QR/intent, url will start with “upi://pay”
2. UPI – Mandate (Create Mandate): Mandate URL will start with “upi://mandate” (Payee
generated mandate string) or “upi://collect” (Payer generated mandate string) and
will also be signed as per signing logic defined.
3. International QR: URL will start with “upiGlobal://” and will be signed as per signing
logic defined.
a. International QR specification (applicable only for international QR):
upiGlobal://pay?purpose=11&param-name=param-value&paramname=param- value&...
4. Domestic UPI QR/ Intent URL specification: upi://pay?param-name=paramvalue&param-name=param-value&...
a. Mandate URL specification (applicable only for Create mandate):
upi://mandate?pa=&pn=&mn=&tid=&type=&validitystart=&validityend=&am=&a
mrule=&recur=&recurvalue=&recurtype=&tr=&url=&cu=&mc=&tn=&sign=&orgid
=& mode=&purpose=
b. Mandate URL specification (UPI mandate created by Payer):
The specification below will be used for mandates which are already authorised
by the Payer and only need to be executed by Payee by simply scanning the QR.
upi://collect?umn=&am=&tn=&validitystart=&validityend=&amrule=&pa=&sign=
&o rgid=&mode=&purpose=
5. Following are the definitions for the header used in the table below:
a. S - Static QR
b. D - Dynamic QR
c. M – Mandatory
d. O – Optional
e. C – Conditional
6. All UPI applications should mandatorily scan all the tags present in the QR/ Intent
(Both optional or mandatory) and pass. The values should not be edited by the (PSP)
or the customer (Only amount tag to be editable in presence of a MAM tag).
7. Where param-name can be any of the valid parameters (based on mandatory vs
optional) listed in below table.

6

Strictly Private and Confidential

Parameter
ver

UPI API Field
Txn>>qr>>qver

Data Type
String

Length
Fixed value

URL Type
S

D

C

M

Description
Version of the QR
ver = 01
Mandatory if purpose = 11, 62, 66

mode

Txn>>initiationMode

String

Fixed value

C

M

Mode of initiating the transaction
List of values:
01 = Offline static QR code
02 = Offline static signed QR code
04 = Intent
05 = Secure intent
15 = Offline dynamic QR code
16 = Offline dynamic signed QR code
22 = Online dynamic QR code
23 = Online dynamic signed QR code
Mandatory if purpose = 11,62, 66

purpose

Txn>>purpose

String

Fixed value

7

C

M

Purpose of the transaction
List of values:
00 = Default
11 = Global UPI Acceptance
62 = International FCY e-commerce
66 = International INR e-commerce

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
Mandatory in string only w.r.t, above
mentioned use case defined by NPCI, else
optional.
If present, Payer PSP to pass as it is, else
Payer PSP to populate ‘00 default’.

orgid

Payee>>Institution>>ne String
tInstId

Min: 6
Max: 12

C

C

Org ID of the acquiring bank/ PSP.
If purpose = 11, 62, 66 then it shall contain
the international institution ID assigned by
NIPL.
Mandatory if purpose = 11, 62, 66

tid

Txn>>id

String

35

O

O

Transaction ID is the 35-digit ID generated by
Payer PSP.

tr

Txn>>refid

String

Max:35

C

M

Transaction reference ID. This could be the
order number, subscription number, bill ID,
booking ID, insurance renewal reference,
etc.
Mandatory if purpose = 11, 62, 66

tn

Txn>>note

String

Max: 50

O

O

Transaction note providing a description of
the transaction.

category

Txn>> refCategory

String

Fixed value

C

C

Mandatory if URL is present in the QR string.

8

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
02 - Invoice

url

Txn>>refurl

String

Max: 99

O

O

A URL, when clicked provides the customer
with further transaction details like complete
billdetails, bill copy, order copy, ticket
details, etc. This can also be used to deliver
digital goods such as mp3 files, etc., after
payment. This URL, when used, must be
related to the particular transaction and
must not be used to send unsolicited
information that is not relevant to the
transaction.

pa

Payee>>addr

String

Max: 255

M

M

It is the Payee UPI ID.
UPI ID consists of an alias of the Payer
followed by the bank identifier.
(Ex:abc.123@bank)
Permitted special characters are dot ‘.’ at ‘@’
and hyphen ‘-’
Total length of UPI ID is inclusive of the bank
identifier.

pn

Payee>>name

String

Max: 99

M

M

Name of the Payee

mc

Payee>> mcc

Numeric

4

C

M

Payee Merchant Category Code assigned by
the acquirer.
Mandatory if purpose = 11, 62, 66

9

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

D

Description

am

Payee&Payer>>Amount Numeric
>> Value

Min: 1
Max: 15

O

M

Format: 2 digits after decimal
If ‘am’ not present (static) or
If ‘mam’ is populated
and ‘am’ value is non- zero (dynamic), then
‘am’ field is editable.

mam

Txn>> Rules>>
MINAMOUNT

Min: 1
Max: 15

O

O

Format: 2 digits after decimal

Numeric

Minimum amount to be defined by Payee
PSP. It should always be an INR value greater
than zero.
E.g., Amount = 100.00

cu

Payee>> Amount>>curr String

3

O

O

It is a 3-digit alpha currency code, as defined
by ISO8583.
The mobile application will be used to
display a recognisable currency to the
consumer, whenever an amount is being
displayed or whenever the consumer is
prompted to enter an amount.
This currency field is used for settlement.

mid

Payee>>
Merchant>>mid

String

Max: 20

C

10

M

Merchant ID

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
Mandatory if purpose = 11, 62, 66

msid

Payee >>Merchant>>sid String

Max: 20

C

M

Merchant Store ID.
Mandatory if purpose=11, 62, 66

mtid

Payee>> Merchant>>tid String

Max: 20

C

M

Merchant terminal ID.
Mandatory if purpose = 11 & 62

mType

Payee>>Merchant>>
Identifier>>merchant
Type

String

Fixed value

C

M

Type of merchant.
List of values:
LARGE | SMALL
Mandatory if purpose = 11, 62, 66

mGr

Payee>>Merchant>>
Identifier>>merchant
Genre

String

Fixed value

C

M

Merchant genre to identify online and offline
merchants.
List of values:
ONLINE | OFFLINE
Mandatory if purpose = 11, 62, 66

mOnboarding Payee>>Merchant>>Ide String
ntifier>> onboarding
type

Fixed value

11

C

M

Merchant onboarding type denotes the
entity. Onboarding the merchant.

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
List of values:
BANK | AGGREGATOR | NETWORK | TPAP
Mandatory if purpose = 11, 62, 66

mLoc

brand

cc

Payee>>Merchant>>
Identifier>>merchant
Loc

String

Fixed value

C

M

Country or city of the merchant.
Mandatory if purpose = 11, 62, 66

Payee>>Merchant>>Na
me
>>brand

Fixed value

Payee>>Institution>>co Numeric
nCode

2

C

M

Brand name of the merchant.
Mandatory if purpose = 11, 62, 66

C

C

Indicates the country code of the merchant.
(A 2-character alphavalue, as defined by
ISO 3166-1)
Mandatory if purpose = 11, 62, 66

bAm

Amount>>Split>> base
amount and value

Numeric

Min: 1
Max: 15

O

C

Base amount will contain the purchase
amount in Payee currency.
Format: 2 digits after decimal
E.g. Amount = 100.00
Mandatory if purpose = 11, 62, 66

bCurr

Amount>>Split>>

String

3

C

12

C

It is 3-digit alpha currency code value, as
defined by ISO8583.

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D

base currency andvalue

This value will be used by the mobile
application to display a recognisable
currency to the consumer whenever an
amount is being displayed or whenever the
consumer is prompted to enter an amount.
Mandatory if purpose = 11, 62

qrMedium

Txn>> QR>> qrMedium

Fixedvalue

Fixed value

M

M

Source channel, i.e., creation point of the
string.
01 = PICK FROM GALLERY
02 = APP
03 = POS
04 = PHYSICAL/ Share
Intent mode
05 = ATM
06 = WEB
To generate the string, code 02 to 06 to be
used.
Code 01 = Pick from gallery, applicable only
to Payer PSP to identify and pass.

Invoice
number

Payee>>Merchant>>
Invoice >> Num

Alphanumeric

Max: 20

C

13

C

This field is used to capture the bill/ invoice
number.

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
If this tag is present, app should display
value to the customer.
Mandatory if purpose = 11, 62

invoiceDate

Payee>>Merchant>>
Invoice >> Date

GMT format

O

C

This field is used to capture the bill invoice
date.
Mandatory if purpose = 11, 62

invoiceName

Payee>>Merchant>>
Invoice >> Name

Alphanumeric

Max: 99

C

O

This field is used to track the unique
customer’s name present in the bill.
If this tag is present, app should display
value to the customer.
Mandatory if purpose = 11, 62

QRexpire

Txn>>QR>>expireTs

GMT format

O

O

Timestamp when the QR expires.

QRts

Txn>>QR>>Ts

GMT format

O

O

Timestamp when QR was created. In case it
is present, app should state that the QR was
created on this timestamp

split

Payee>> Amount>> split String
>> name&value

O

O

It will contain the split details of amount.
The PSP must compute amount value and tip
amount to show the final amount to the
customer for PIN authorisation.

Max: 255

14

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
(one or more split value will come)
CONFEE: 30 | CONPCT: 2% | TIPS: 1 |
DISCNT: 10% | DISPCT: 10 | FX: 30 | MKUP:
5%

pinCode

Merchant>>identifier>> alphanumeric
pinCode

Max: 10

O

O

PIN code or postal code of the merchant.

Tier

Merchant>>Identifier>> Fixedvalue
Tier

Fixed value

O

O

Denotes the tier of the city on the basis of
population.
TIER1 | TIER2 | TIER3 | TIER4 | TIER5 | TIER6

txnType

txn>> type

String

Fixed value

O

O

It denotes the type of transaction.
List of values:
PAY
COLLECT
CREATE
UPDATE
REVOKE
PAUSE
UNPAUSE

mn

Mandate>>name

String

Max: 99

O

C

Mandate name specifies the purpose of the
mandate.
Applicable only for mandate URL.

type

Mandate>>type

String

Max: 99

O

15

C

Future use.

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
Applicable only for mandate URL.

validitystart

Mandate>>validity>>
start

String

M

C

Defines start time of mandate validity
(Format DD-MM-YYYY)
Applicable only for mandate URL.

validityend

Mandate>> validity>>
start

String

M

C

Defines end time of mandate validity.
(FormatDD-MM-YYYY)
Applicable only for mandate URL.

amrule

Mandate>>Amount>>
rule

String

O

C

‘MAX’ or ‘EXACT’ rule applied to mandate
(Optional, default valueto be passed in
online message in case a rule is not passed
in QR is 'MAX')
Applicable only for mandate URL

recur

Mandate>> Recurrence String

Fixed value

M

C

Specifies the frequency of mandate debit.
(ONETIME | DAILY | WEEKLY | FORTNIGHTLY |
MONTHLY | BIMONTHLY | QUARTERLY |
HALFYEARLY | YEARLY | ASPRESENTED)
Applicable only for mandate URL.

recurvalue

Mandate>>
Recurrence >>rule
>>value

String

Max: 99

O

C

Specifies date along with 'recurtype' for
debit. (For future use)
Applicable only for mandate URL.

recurtype

Mandate>>Recurrence
>>rule>>type

String

Fixed value

O

C

Can have values: (BEFORE | ON | AFTER),

16

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
Specifies date along with 'recurvalue' for
debit.
Applicable only for mandate URL.

rev

rev = Y/N

String

Fixed value

O

C

Revocable tag can be passed as Y/N.
In case this tag is not present in the QR,
app should by default pass the value as ‘Y’.
Applicable only for mandate URL.

share

share = Y/N

String

Fixed value

O

C

Share to Payee option can be given as Y/N. In
case the tag is not present in the QR,
customer will have the option to opt for the
same in the app.
Applicable only for mandate URL.

block

block – Y/N

String

Fixed value

O

C

This field is used for intimating the remitter
bank to block the necessary funds against
customer account.
Applicable only for mandate URL

umn

Payer>>addr

String

35

O

17

C

Unique mandate number shared by the Payer
for the Payee to initiate the debit.
(For future use when other type will be
included)

Strictly Private and Confidential

Parameter

UPI API Field

Data Type

Length

URL Type
S

Description

D
Applicable only for mandate URL.

skip

String

2

O

O

(For future use) Mandate can be executed for
a non–registered mandate, i.e., mandate is
not present with Payee PSP.
Applicable only for mandate URL.

sign

String

C

M

Digital signatures need to be passed in this
tag.(It is used for securing the string).
Parameter optional for UPI Global
Acceptance and mandatory for Domestic
QR.

18

Strictly Private and Confidential

Developers who are developing merchant applications and mobile apps that need
to integrate UPI payment should form URL within their application and then do either of
the following:
1. If the application and PSP UPI application is within the same mobile, then do a deep
linking using the URL.
2. Create a QR code within the application and allow customers to scan it and invoke
their UPI application.
3. Use alternate transfer protocol (such as BT, Wi-Fi Direct, NFC, Sound, etc.), to
transfer the URL data to customer mobile on which it gets deep linked to their PSP
application.
4. While reading a QR and/or intent all parameters must be read and passed to online
message.
5. If any tag is not present, it can be dropped or passed as null.
6. Using a standard data format and URL scheme allows the actual protocol of data
transfer to be separated, thereby allowing any transfer protocol to be used to transfer
this from one device to another.

3.2 SIGNATURE
Merchants can initiate intent from their mobile application and/or generate signed QR
from their terminal, PoS, and exit sensors. All the mentioned protocols for merchantinitiated method follows identical processes for signing and verification.
1. Key generation: Merchant, or the acquiring bank on behalf of the merchant, needs to

generate a key pair (public and private key with ECDSA 256 + SHA 256 specifications.
If acquiring bank has generated the key pair, then private key can either be sharedwith
the merchant for intent generation or can be integrated in Software Development Kit
(SDK) directly. Merchant and banks shall also add provision for update of key pairs.

2. Key upload: Then merchant needs to share this public key with its acquiring bank.

Then the acquiring bank will upload its merchant public key on UPI with Manage VAE
API. If acquiring bank has generated the key for its merchant, then it can directly
upload on UPI.

19

Strictly Private and Confidential

3. Signing of intent:

Step 1: The merchant should get the required details from the customer and form an URN.
Sample Inputs
//URN
"upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe1234
5hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www.
test.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu=
INR&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CGST:08.45
|SGST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50+05:30&invoiceName=Dummy%20Customer&QRexpire=2019-0611T13:21:50+05:30&QRts=2019-06-12T13:21:50+05:30&pinCode=
400063&tier=TIER1&gstIn=GSTNUM1234567890"
Sample Output
//URN intentURL:
"upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe1234
5hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www.
test.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu=
INR&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CGST:08.45
|SGST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50+05:30&invoiceName=Dummy%20Customer&QRexpire=2019-0611T13:21:50+05:30&QRts=2019-06-12T13:21:50+05:30&pinCode=400063
&tier=TIER1&gstIn=GSTNUM1234567890"
Step 2: The specified URN needs to be signed using ECDSA with SHA256 algorithm.
Sample Inputs
//Signature with Sha-256
Signature dsa = Signature.getInstance("SHA256withECDSA");
dsa.initSign(privKey);
String intentURL
="upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe123
45hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www
.test.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu
=INR&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CGST:08.4
5|SGST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50+05:30 &invoiceName=Dummy%20Customer& QRexpire=2019-0611T13:21:50+05:30 &QRts=2019-06-12T13:21:50+05:30&pinCode
=400063&tier=TIER1&gstIn= GSTNUM1234567890";
System.out.println("\nintentURL:" + intentURL);
byte[] strByte = intentURL.getBytes("UTF-8");
dsa.update(strByte);
//Sign with private key byte[] realSig = dsa.sign();

20

Strictly Private and Confidential

Sample Output
Private Signing Output
3046022100da68400bd3a56c9fd68d21aacfedd6a2f3f87d70cad5bee61efae972
d2b60833022100f463cfa0a3d59a1d0cb7ff3592066275b8832a44f380cd0f3444
4d04d8d48a4c
Step 3: The output of the signature should be encoded with base64.
Sample Input
//Encode signed URL with base 64 String encodedSign =
java.util.Base64.getEncoder().encodeToString(realSig);
Sample Output Encoded
Signature:MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz
6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM
Step 4: The final encoded value should be appended PoS delimiter “sign=” to original
URN.
Sample Input
//Append with Signed URL
String finalBHIMURL = intentURL+"&sign="+encodedSign;
System.out.println("\nSignature: " + new BigInteger(1,
realSig).toString(16));
System.out.println("\nEncoded Signature:" + encodedSign);
System.out.println("\nFinal BHIM URL:" + finalBHIMURL);

Sample Output
Final Output URL:
upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe12345h
s29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www.te
st.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu=IN
R&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CGST:08.45|S
GST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50+05:30&invoiceName= Dummy %20Customer&QRexpire=2019-0611T13:21:50 +05:30&QRts=2019-06-12T13:21:50+ 05:30&pinCode=400063
&tier=TIER1&gstIn= GSTNUM1234567890&sign=MEYCIQD
aaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYn
W4gypE84DND zRETQTY1IpM

21

Strictly Private and Confidential

The above example is an android intent sample initiated by merchant
(‘merchant@npci’ with mcc ‘5411’). Hence, mode is ‘05’ and orgID is ‘700004’.
4. Key download: Payer PSP server needs to download all merchant keys and cache it

on their server. This cache needs to be updated daily by the PSP server. Each public
key downloaded must be mapped with the merchant UPI ID for which the key was
uploaded.

5. Searching the key: OrgID and UPI ID of Payee need to be extracted first. As the orgID

‘000000’, the public key needs to be looked in list VAE cache with UPI ID as search
parametre. This key will be used for verifying the signature.

3.3 VERIFYING THE INTENT
Step 1: The signature part needs to be extracted and separated from the original text of
the encrypted code.
Step 2: Then the appended value must be decoded with base64.
Sample Input
//Decode the signed URL with base 64
String[] bhimReceivedURL = finalBHIMURL.split("&sign="); byte[]
decodedSign =
java.util.Base64.getDecoder().decode(bhimReceivedURL[1]);
System.out.println("\nDecoded
Signature: "
+
new
BigInteger(1,
decodedSign).toString(16));

Sample Output
Decoded Signature:
3046022100da68400bd3a56c9fd68d21aacfedd6a2f3f87d70cad5bee61efae972
d2b60833022100f463cfa0a3d59a1d0cb7ff3592066275b8832a44f380cd0f3444
4d04d8d48a4c

Step 3: The entire intent string, excluding the signed part, will be passed into verify
function along with signature and the public key of the merchant for verification.
Sample Input
//Initialise verification with public key dsa.initVerify(pubKey);
//Initialise using plain text bytes
dsa.update(bhimReceivedURL[0].getBytes("UTF-8"));
//Verify against sign
boolean verified = dsa.verify(decodedSign);
System.out.println("\nSignature Verify Result:"+verified);

22

Strictly Private and Confidential

Sample Output
Signature Verify Result: true

3.4 ACTIONS
1. If the verification is successful, then the application should bypass the passcode
page.
2. If verification is failure, either due to corruption or tampering the signature, then the
intent request must be declined stating ‘intent is tampered or corrupt’.
3. If signature is not present in intent, then the application should show warning
message to user that the ‘source of intent could not be verified’ and shall request
passcode to proceed with the payment.
a. Invoice in the box
UPI has a provision where the merchants can share bills/invoices with the customers
before the transaction is authorised. The bills/invoices can either be downloaded as PDF
or can be viewed on a browser. This provision requires the PSP applications to display an
option called ‘view invoice’. This option will be present for intent/QR initiated pay
transactions.
When the user scans a QR or triggers an intent carrying URL tag, then he will get an option
on the app to click that URL. This URL will redirect him to the invoice which can be either
viewed or downloaded.

4. NOTE
url: The parameters present in the URL should be passed as they are in the online
message by the PSP application. The URL always starts with http or https. i.e. url=https://
or url=http://
Checks on the URL which are to be performed by the apps on security, source generation,
coneed, etc., need to be specified.
mam: This parameter is conditional and shall be used to define a minimum amount rule
where amount field in PSP app is editable. If mam tag is not present or ‘mam=null’ or
‘mam=’ then amount field should not be editable.
Note: If a customer enters the value less than value passed in mam then UPI will
decline the transaction. To reduce such declines, PSP applications should not
allow the entry of amount below mam value.

23

Strictly Private and Confidential

Null values: This needs to be handled by PSP as null value and should not passed into
online message directly as a string value “null”.
Space: Space shall be handled as per the method below:
While generating/creating/reading a QR, intent, NFC, BLE, UHF, etc., space(“ ”) should be
represented as “%20” and not “%”as to be compliant with existing Internet Standard RFC
3986 section 2.1 Percent-Encoding.
Note: Considering that the current PSP apps are developed to read “%” as space
(“ ”), the bank PSP should support both “%” and “%20” till such time the
ecosystem is aligned to the revision. Hence, backward compatibility should be
ensured.
Mid, msid, mtid will be used by acquiring bank/merchant forreconciliation / confirmation
purposes. This will be echoed in all messages.

5. RESPONSE PARAMETERS
As a standard practice, merchant apps must check the final status with their
server/PSP server. Following is a recommendation on the data returned from the
bank/PSP app to the merchant app.
Parameter Name

M/O/C

Data Type

Description

txnID

M

String

Transaction ID from the online
message.

response Code

M

String

UPI response code.

ApprovalRefNo

O

String

UPI approval reference number
(beneficiary).

Status

M

String

Status of the transaction
(SUBMITTED/SUCCESS/FAILU
RE).

txnRef

M

String

Transaction reference ID passed
in input.

appId

M

String

Payer application ID, where
Customer inputs UPI PIN.

Ex 1:
txnId=abcdefghijklmnopqrstuvwxyz123456789&responseCode=00&ApprovalRefNo=12
2321&Status=SUCCESS&txnRef=6655443322&appId=com.bhim

24

Strictly Private and Confidential

Ex 2:
txnId=abcdefghijklmnopqrstuvwxyz123451234&responseCode=ZM&ApprovalRefNo=&S
tatus=FAILURE&txnRef=6655443322&appId=com.bhim
Ex 3:
txnId=abcdefghijklmnopqrstuvwxyz123454321&responseCode=Y1&ApprovalRefNo=nul
l &Status=FAILURE&txnRef=6655443322&appId=com.bhim
Mandatorily, the final response should be sent back to the initiating application incase
of an Intent. The bank application may need to whitelist the merchant app URL.

6. IMPLEMENTATION SAMPLES
6.1 HYPERLINK (INTENT URL)
The user goes to an e-commerce website on his/her mobile phone and places an order.
The website generates a link, which the user can click on, to complete the payment.
As per the specification, the link contains the Payee details, the transaction reference
(order ID), and the transaction amount.
Example:
upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe12345
hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www.t
est.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu=I
NR&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CG
ST:08.45|
SGST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-06-11
T13:21:50+05:30&invoiceName=Dummy%20Customer&QRexpire=2019-06- 11T
13:21:50+05:30&QRts=2019-06-12T13:21:50+05:30&pinCode=400063&tier
= TIER1
&gstIn=GSTNUM1234567890&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h
9cMrVvuYe+uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM
When the user clicks on the link on his mobile browser, it invokes the local PSP
application, where the user can confirm the details, and complete the payment.
Because of design simplicity, user familiarity with hyperlinks, and ease of sharing, such
links can be generated and shared across multiple communication channels, such as
email, chat, and social networks.

25

Strictly Private and Confidential

6.2 QR CODE
QR code consists of black modules arranged in a square pattern on a white background.
The information encoded can be made up of four standardised kinds (“modes”) of data
(numeric, alphanumeric, byte/binary, Kanji), or by supported extensions, virtually any
kind of data.
QR codes can be used for proximity payments with UPI. Developers who are developing
merchant applications must generate a URL fully compliant to specification in previous
section and then create a QR code of that URL.
Example:

upi://pay?ver=01&mode=16&orgId=159992&tid=NPCI8cdd79c7391467cb7698
8fe8bbccebc&tr=MerRef123&tn=Merchant%20QR&category=02&url=https://
www.test.com&pa=merchant@npci&pn=Merhcant&mc=5411&am=100.00&cu=INR
&mid=12343 &mtid=12343&qrMedium=06&QRexpire=2019-0611T13:21:55+05:3
0&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz6C
j 1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM
Note to PSPs: Considering the simplicity, openness, and wide acceptance of QR
codes and its ability to be printed, displayed on PoS devices, and various screens,
etc., PSP applications are encouraged to include a QR code scan option within
their UPI application so that customers can use a single app to scan and pay.

26

Strictly Private and Confidential

Sample QR
Merchant presented singed dynamic QR generated on PoS.
upi://pay?ver=01&mode=16&orgid=159992&tid=NPCI8cdd79c7391467cb7698
8fe8bbccebc&tr=MerRef123&tn=Merchant%20QR&category=02&url=https://
www.test.com&pa=merchant@npci&pn=Merchant%20Name&mc=5411&am=1000.0
0&mid=12343&msid=56789&mtid=12343&qrMedium=03&QRexpire=2019-0611T13:21:55
+05:30&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAP
R jz6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM

1) Merchant presented singed dynamic GST QR generated on PoS.
upi://pay?ver=01&mode=16&orgid=700004&tid=TESTGST123456qazqwe12345
hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&pa=merchant@mypsp2&pn=Test%20
Merchant&mc=5411&am=100.00&mid=TST5432&msid=TSTABC123&mtid=TSTABC1
234&gstBrkUp=CGST:08.45|SGST:08.45&qrMedium=03&InvoiceNo=BillRef12
3&invoiceDate=2019-0611T13:21:50+05:30&invoiceName=Dummy%20Customer& QRexpire=2019-0611T13:21:50+05:30&pinCode=400063&tier=TIER1&gstIn=
GSTNUM1234567890&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly
0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM

27

Strictly Private and Confidential

2) Merchant presented singed static QR code generated and pasted near counter.
upi://pay?ver=01&mode=02&orgid=159992&tr=MerRef123&tn=Merchant%20Q
R&pa=merchant@npci&pn=Merchant%20Name&mc=5411&mid=12343&msid=56789
&mtid=12343& qrMedium=04&QRexpire=2020-0611T13:21:55+05:30&pinCode= 400063&
tier=”Tier1”&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0
rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM

3) Merchant presented GST singed static QR code generated and pasted near
counter.
upi://pay?ver=01&mode=02&orgid=159992&tr=MerRef123&tn=Merchant%20Q
R&pa=merchant@npci&pn=Merchant%20Name&mc=5411&mid=12343&msid=56789
&mtid=12343& qrMedium=04&QRexpire=2020-0611T13:21:55+05:30&pinCode= 400063&tier=
”Tier1”&gstIn=GSTNUM1234567890&sign=MEYCIQDaaEAL06Vsn9
aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DN
DzRETQTY1IpM

28

Strictly Private and Confidential

4) Merchant presented singed dynamic QR (International) generated on PoS.

upiGlobal://pay?ver=01&mode=16&purPOSe=11&orgid=1599910001&tid=NPC
I8cdd79c7391467cb76988fe8bbccebc&tr=MerRef123&tn=Global%20Merchant
&pa=globalmerchant@npci&pn=Global%merchant&mc=5411&mid=123412&msid
=32
1231&mtid=123123&cc=SG&bAm=36.00&bCurr=SGD&qrMedium=03&invoiceNo
=BillRef123&invoiceDate=2019-06-11T13:21:50+05:30&
invoiceName=Global%20 Merchant&QRexpire=2019-06-11T13:21:50+05:30&
sign=MEYCIQDaaEAL06Vsn9
aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DN
DzRETQTY1IpM

5) Merchant presented singed static QR (International) and pasted near counter.

upiGlobal://pay?ver=01&mode=02&purPOSe=11&orgid=1599910001&tr=MerR
ef123&tn=Global%20Merchant&pa=globalmerchant@npci&pn=Global%mercha
nt&mc=5411&mid=123412&msid=321231&mtid=123123&cc=SG&bCurr=SGD&qrMe
dium=04&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50+05:30&invoiceName
=Global%20Merchant&sign=MEYCIQDaaEAL06Vsn9aNIarP7dai8/h9cMrVvuYe+
uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4gypE84DNDzRETQTY1IpM

29

Strictly Private and Confidential

6) Person presented signed Dynamic QR.
upi://pay?ver=01&mode=22&orgid=159991&tid=NPCI8cdd79c7391467cb7698
8fe8bbccebc&tr=4894398cndhcd23&tn=P2P%20Transaction&pa=deepak@npci
&pn=Deepak%20Gupta&mc=0000&am=1000.00&qrMedium=02&sign=MEYCIQDaaEA
L06Vsn9aNIarP7dai8/h9cMrVvuYe+uly0rYIMwIhAPRjz6Cj1ZodDLf/NZIGYnW4g
ypE84DNDzRETQTY1IpM

6.3 OTHERS
UPI linking is protocol agnostic and hence, allows innovative mechanisms between
merchant/proximity devices to send a UPI intent to customer phones.

For example, a merchant oapplication could create the UPI link (as per specifications
share in the previous section) and then transmit using sound to the customer device.
CustomerPSP app or a utility app can listen to that sound, convert it back to the link, and
then launch the UPI application on customer phone to make the payment.
Note: There can be 3rd party general purpose utility applications that allow users
to scan these QR codes, launch the link, allow other innovative transfer protocols
using sound, etc. Such apps can work as a proxy utility that sends/receives these
links and then launch the appropriate apps that are listening to these intents.

30

Strictly Private and Confidential

7. APPENDIX
import java.math.BigInteger; import java.security.KeyPair;
import java.security.KeyPairGenerator; import
java.security.PrivateKey;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.ECGenParameterSpec; public class TestECC
{ public static void main(String args[]) {
try {
KeyPairGenerator kpg = KeyPairGenerator.getInstance("EC");
System.out.println(kpg.getAlgorithm());
ECGenParameterSpec ecsp = new ECGenParameterSpec("secp256r1");
kpg.initialize(ecsp); //ecsp
KeyPair kyp = kpg.genKeyPair(); PublicKey pubKey =
kyp.getPublic(); PrivateKey privKey = kyp.getPrivate();
System.out.println("\n\n");
//Signature with Sha-256
Signature dsa = Signature.getInstance("SHA256withECDSA");
dsa.initSign(privKey); String intentURL =
"upi://pay?ver=01&mode=05&orgid=700004&tid=TESTGST123456qazqwe1234
5hs29hnd1qa2&tr=MerRef123&tn=GST%20QR&category=02&url=https://www.
test.com&pa=merchant@npci&pn=Test%20Merchant&mc=5411&am=100.00&cu=
INR&mid=TST5432&msid=TSTABC123&mtid=TSTABC1234&gstBrkUp=CGST:08.45
|SGST:08.45&qrMedium=02&invoiceNo=BillRef123&invoiceDate=2019-0611T13:21:50 +05:30&invoiceName=Dummy%20Customer&QRexpire=2019-0611T13:21:50+05:30&QRts=2019-06-12T13:21:50+05:30&pinCode=400063
&tier=TIER1 &gstIn=GSTNUM1234567890"
System.out.println("\nintentURL:" + intentURL); byte[] strByte =
intentURL.getBytes("UTF-8"); dsa.update(strByte);
//Sign with private key byte[] realSig = dsa.sign();
//Append with Signed URL
String finalBHIMURL = intentURL+"&sign="+encodedSign;
System.out.println("\nSignature: " + new BigInteger(1,
realSig).toString(16)); System.out.println("\nEncoded Signature:"
+ encodedSign); System.out.println("\nFinal BHIM URL:" +
finalBHIMURL);
//Decode the signed URL with base 64

31

Strictly Private and Confidential

String[] bhimReceivedURL = finalBHIMURL.split("&sign=");
byte[] decodedSign =
java.util.Base64.getDecoder().decode(bhimReceivedURL[1]);
System.out.println("\nDecoded Signature: " + new BigInteger(1,
decodedSign).toString(16));
//Initialise verification with public key
dsa.initVerify(pubKey);
//Initialise using plain text bytes
dsa.update(bhimReceivedURL[0].getBytes("UTF- 8"));
//Verify against sign
boolean verified = dsa.verify(decodedSign);
System.out.println("\nSignature Verify Result:"+verified);
}
catch (Exception e)
{
System.out.print(e);
}
}
}

32