Open API >QR Code Payments >UPI QR Code App Gateway
UPI QR Code App Gateway
QR Code Payments Issuer Mobile Payment
UPI QR Code is a low-cost, convenient and secure payment solution. Through UPI system with APIs, mobile App providers outside of mainland China will be able to provide UPI QR Code payment service to their users.
API Introduction
API Introduction
What is it?

UPI QR Code product can be integrated into mobile Apps to support a low-cost, convenient and secure innovative payment method, where consumers can either display a payment QR Code for merchants to scan (Consumer-Presented) or scan merchant's static/dynamic QR Code (Merchant-Presented) to enter payment amount.  

This set of APIs provide all the necessary functions, allowing mobile App providers to connect to UPI system and support UPI QR Code payment in both Merchant-Presented and Consumer-Presented mode.


Key Features

Cost-effective

UPI QR Code is a low-cost payment solution that can work on any smart phone with screen and camera, and on any mobile OS platform, including Android and iOS, with no reliance on mobile phone manufacturers for cardholders.


Security

Security is a basic requirement for payments. UPI adopts various anti-risk measures to ensure whole transaction’s safety, including CDCVM evolved from PIN or signature for user's authentication & verification, together with tokenization technology to avoid exposure risk of card or account info.


Interoperability

UPI QR Code is compatible with EMVCo standard, making it standardized and globally interoperable. 


Integrity

UPI QR Code payment sticks to four-party mode which is consistent with bank card transaction except for information interaction. UPI QR Code payment has a whole integrated business mechanism, risk control and techniques to assure cardholders' capital safety.


When to Use it?

When mobile App providers want to integrate UPI QR Code Payments function and connect to UPI system to provide QR Code payment service to their users.

Who Use it?
Mobile App providers outside of mainland China (Could be issuers, merchants, third-party payments companies and software developers)
Where to Use it?
This API is available globally except for mainland China
Things to Know

1. APIs in QR Code App Gateway include message flows and message requirements for mobile App gateway to support UPI QR Code payments, such as PAN enrollment, Account Verification, Token service, Lifecycle management of cards, etc. Please find 16 APIs in ‘APIs Included’ column. 

2. Mobile App shall support both Merchant-Presented and Consumer-Presented QR Code payments mode to work in different scenarios;

3. Mobile App that integrate UPI QR Code payment shall support both EMV mode (mainly used outside of mainland China) and URL mode (mainly used in mainland China)

4. Before using QR code payment service, mobile App shall guide users to link intra-bank/inter-bank UnionPay card in that App. Users provide card no. and pass cardholder identification and OTP verification to complete card registration. 

5. Customer-Presented QR Code: When consumer clicks “QR Code Pay” in the App main page, App will request both EMV QR code and URL mode barcode from UnionPay system and display them separately for merchant to scan. When App fails to detect consumer’s location, it shall allow users to manually switch the QR Code by clicking “Global QR Code” or “QR Code in China” at the bottom of the page.

6.Merchant-Presented QR Code: Merchant-Presented QR Code payment allows consumers to scan merchants’ QR code, then initiate payment in the mobile App. After completing transaction, both merchant and consumer will receive notification.

7.For encoding specification of consumer-presented and merchant-presented code, please refer to 'Documentation' column.

8.It is recommended to use JAVA to test QR App Gateway interfaces


Flow Chart
Flow Chart

QR CODE App gateway.png

API Reference
API Reference
  • Pan Enrollment
  • Account Verification
  • Sending OTP
  • Token Provisioning
  • Token State Update
  • Cardface Downloading
  • Token Request
  • Token State Notification
  • Mpqrc Payment Emv
  • Trx Result Inquiry
  • Qrc Info Inquiry
  • Mpqrc Payment Url
  • Cpqrc Generation
  • Additional Processing
  • Additional Processing Result
  • Trx Status Notification
Interface description
The mobile application allows the user to scan or enter the details of existing cards in order to digitize these cards. The application gateway sends PAN_ENROLLMENT request to the UPI.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Message Information msgInfo object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the application provider initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+serial code
Time Stamp timeStamp N 14 M:Mandatory Format : YYYYMMDDhhmmss . The value in the response must match the value in the request. Example:"20170714235911". Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "PAN_ENROLLMENT".
Wallet ID walletID AN 8 M:Mandatory The distinctive value associated to a wallet "00010344"
Transaction Information trxInfo object M:Mandatory
Device ID deviceID ANS 1-64 M:Mandatory The distinctive value associated to a device
Primary Account Number pan AN 48 M:Mandatory Encrypted with the public key of the Encryption Certificate. Please refer to Encrypt sample code in Documentation
Risk Information riskInfo object O:Optional
GPS gps ANS 1-64 O:Optional Components: +(-) latitude/+(-) longitude "+37.12/-121.23"
SIM Card simCard array 1-200 O:Optional The mobile number of the SIM cards. The mobile phone may have more than one SIM card.  
Application User ID appUserID ANS 1-64 O:Optional An alias for the application user ID.  
User Enrollment Date usrEnrolDate N 6 O:Optional The date when the cardholder registers in the wallet. "161230" Format:(YYMMDD)
Card Number Capture Method captureMethod ANS 1-64 O:Optional Valid Values: "MANUAL" "NFC" "CAMERA" "UNKNOWN" "MANUAL"
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device  
Device Type deviceType ANS 1-20 O:Optional Valid Values: “MOBILE” Reserved Values: “WATCH” “PAD” “PC”
Device Score deviceScore N 1 O:Optional Valid Values: “1” to “5”;“5” indicates the device is very reliable, and “1” indicates the device is less reliable.
Certificate and Signature certificateSignature object M:Mandatory
Application Signature Certificate ID appSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The application gateway uses the private key of this certificate for signature.
UMPS Encryption Certificate ID umpsEncCertID AN 128 C:Conditional The serial number of the certificate. The application gateway uses the public key of this certificate for encryption.
Signature signature ANS 1-2048 M:Mandatory Please refer to the Signature for details
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message Information msgInfo object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the application provider initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+serial code
Time Stamp timeStamp N 14 M:Mandatory Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "PAN_ENROLLMENT".
Wallet ID walletID AN 8 M:Mandatory The distinctive value associated to a wallet. "00010344"
Transaction Information trxInfo object M:Mandatory
Device ID deviceID ANS 1-64 M:Mandatory The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile.
Enrollment ID enrolID N 16 C:Conditional It is used to match the message sets within an enrollment process. The Enrollment ID is populated by UnionPay system and shall be the same in all related messages: PAN_ENROLLMENT, ACCOUNT_VERIFICATION, SENDING_OTP, TOKEN_PROVISIONING, TOKEN_STATE_UPDATE. The value must be unique for each enrollment process..
Cardholder Verification Method cvm array 1-255 C:Conditional Present if the Response Code is "00". List of the cardholder verification (CV) methods required. The mobile application shall collect these information from the cardholder. Valid CVs are : "expiryDate"; "cvn2"; "name"; "idType"; "idNo", "mobileNo". Note1:The "idType" and "idNo" shall be present together. Note 2: If no CV method is required, the object shall be "cvm": [ ] .
TNC ID tncID AN 1-20 C:Conditional The unique identifier of Terms and Conditions (TNC) “TNC01” 
TNC URL tncURL AN 1-50 C:Conditional The URL link displaying the Terms and Conditions  
Message Response msgResponse object M:Mandatory
Response Code responseCode AN 2 M:Mandatory It contains a code that defines the response to a request. Please refer to the Response Code and Message for the valid values. "00"
Response Message responseMsg S 1-100 M:Mandatory It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the consumer of the payment outcome. Please refer to the Response Code and Message for details. "Approved"
Certificate and Signature certificateSignature object M:Mandatory
UMPS Signature Certificate ID umpsSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The UMPS uses the private key of this certificate for signature.
Signature signature ANS 1-2048 M:Mandatory Please refer to the Signature for details
Sample code
Request code
Other
 {"certificateSignature":{"appSignCertID":"1508406698","umpsEncCertID":"59C4A65E","signature":""},"msgInfo":{"msgID":"A3999000220171016093501556176","msgType":"PAN_ENROLLMENT","timeStamp":"20171016093501","versionNo":"1.0.0","walletID":"39990002"},"trxInfo":{"deviceID":"4A728036-3DB0-4723-9CC6-D781CF5EBC1A","pan":"6227899809938060"}}


Response code
Other
{"trxInfo":{"deviceID":"28e5846283dc4b768814d485ff5a401d","enrolID":"216807","cvm":["mobileNo"],"tncID":"27520702","tncURL":"https://www.baidu.com"},"msgInfo":{"versionNo":"1.0.0","msgType":"PAN_ENROLLMENT","msgID":"20200415144742004942","timeStamp":"20200415144742","walletID":"39990004"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"oF9uZ2OWjkoE9bTcBW9VJI6k9OKzcexIu/ZRjQDn2bV4jiK+YSPzJZVo1gQkPeuyr5wz1TKZArSF+ngLSGh2BRbNJ3qa1t7IHnRuMgvo+jivEbtQMw6pHu+N8Avj0G2ruYJAYZEpXT79wjI15N8t6cUFbZkoeZqcm1wE1/cwGDiAyGztdM0X2/Q+YrKfEXc4fRzeiP/VdpStOEF45iuJpgfhVy0pyyygLaYRFDumV6amD2lVBB/ziCVAPsqVQaN9+DRcvnGwZRP3mTdZkIKW3vkj3HWwSZJsmXHN/8yUHBRxSW21OkLEc/rv5KheByPNpzpvZuSqK9wZrTeuENAhuA=="}}


Getting Started
Getting Started

1. Data Elements and Message

Message Format

Messages exchanged between the application gateway and the UMPS shall be in the JSON data interchange format as defined in [RFC 7159].

Message Flow

The solid line in a Sequence Chart 's processing flow indicates that once the flow begins, the message is mandatory. The dotted line indicates that the message is optional or conditional.

Data Elements Dictionary

In each interface, Message Information ("msgInfo") shall always be present and be the first data object of all request and response messages; 

Transaction Information ("trxInfo") contains different data elements according to the Message Type. The Transaction Information may be present in a request message or a response message;

Certificate and Signature ("certificateSignature") Certificate and Signature shall always be present as the last data object of the request messages and response messages. Please refer to Security Requirement for details;

Message Response ("msgResponse") shall always be present in a response message:

• When it is an acknowledgement response, "responseCode”: “00” indicates the request message is well-received. The processing result will be sent in another message later. For example, the “responseCode” of the “ADDITIONAL_PROCESSING” indicates the application gateway has received the request from the UMPS. The result of “ADDITIONAL_PROCESSING” will be sent in the “ADDITIONAL_PROCESSING_RESULT” message.

• When it is a processing result response, "responseCode”: “00” indicates the request message is approved.

Please refer to Response Code Referrence for details.


2. APIs Included

UPI QR Code App Gateway 's 16 APIs can be categorized into following sets and their calling sequence can be found in Sequence Chart.

The set of Account Enrollment APIs performed by the mobile application:

• Pan Enrollment

• Account Verification

• Sending OTP

• Token Provisioning

• Cardface Downloading

• Token State Update


The set of Enrollment Notification APIs performed after mobile application has completed the account enrollment through its own network

• Token Request

 

The set of Token Life Management APIs used to change the Token state in UnionPay system

• Token State Notification


The set of Transaction Processing APIs

In a Merchant-presented QRC-based transaction, the Consumer can make a purchase in a mobile application by scanning the QRC displayed by the Merchant. In a Consumer-presented QRC-based transaction, the Merchant can make a purchase by scanning the QRC displayed in a Consumer mobile device. For encoding specification, please refer to Consumer-presented QR Code and Merchant-presented QR Code in this page. 

APIs included:

• Mpqrc Payment Emv

• Trx Result Inquiry

• Qrc Info Inquiry

• Mpqrc Payment Url

• Cpqrc Generation

• Additional Processing

• Additional Processing Result

• Trx Status Notification


Please be noted that only merchant-presented QRC-based transaction sandbox testing is available now.


Sequence Chart
Sequence Chart

Account Enrollment

The following figure illustrates the flow of account enrollment performed by the mobile application through UnionPay network.

绑卡.png


1. PAN_ENROLLMENT request 

The mobile application allows the user to scan or enter the details of existing cards in order to digitize these cards. The application gateway sends PAN_ENROLLMENT request to the UPI. 

a. Device ID is the unique identifier in the mobile handset, such as Android ID or IMEI number. 

b. Wallet ID is the identifier assigned by the UPI to identify the mobile application, as the Issuer may have more than one mobile application with different risk parameters for the tokens. 

c. PAN is the card number of the payment card 


2. PAN_ENROLLMENT response 

The UPI sends a request to Issuing Host to check the status of the physical card, and returns the result in the PAN_ENROLLMENT response with the following information: 

a. Enrollment ID is the unique identifier to keep track of this account provisioning pro