By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >QR Code Payments >UPI QR Code Acceptance
UPI QR Code Acceptance
QR Code Payments Acquirer Mobile Payment
UPI QR Code is a product of inter-bank switch for mobile payments. Through UPI system with API Interfaces, acquirers outside of mainland China will be able to support UPI QR Code payment for its merchants.
Sandbox Testing
API Introduction
API Introduction
What is it?

UPI QR Code product can be used by UPI QR Code merchants to support a low-cost, convenient and secure innovative payment solution by either displaying a static/dynamic QR Code (Merchant-Presented) or scanning consumer's payment QR Code (Consumer-Presented).

This set of API provides all the necessary functions, allowing acquirers to connect to UPI system with JSON message instead of traditional ISO 8583 message, and supporting UPI QR Code payments in both Merchant-Presented and Consumer-Presented mode.


Key Features

Open

The platform is open. QR Code can be displayed on merchant's app. The transaction can be completed with any APP that can support UPI's QR Code.

Security 

Security is a basic requirement for payments. UPI adopts Tokenization technology which supports risk control for whole transaction process, making sure of safety and preventing leakage of account information.

Interoperability

UPI's QR Code is of EMVCo standard and extendable for future use of compatibility of other international card schemes, which makes QR Code payment in and out of mainland China interoperable.

Integrity

UPI's QR Code payment sticks to 4-party mode which is almost the same with bank card transaction only except for the information interaction. UPI's QR Code payment has a whole integrated mechanism of business, risk control, techniques which makes user's capital secured.


When to Use it?

When UPI QR Code Acquirers want to connect to UPI system and support QR Code payment through JSON interface.

Who Use it?
Acquirer, Third-party payment company and Software developer.
Where to Use it?
This API is available globally except for mainland China
Things to Know

1. UPI highly suggest acquirers to support both Merchant-Presented and Consumer-Presented QR Code payments mode, in order to meet different requirements from merchants and cardholders (consumers);

2. In Merchant-Presented mode, acquirers shall support QR Code generation and verification of transaction message and validity of QR Code info. sent from UPI system.

3. In Consumer-Presented mode, acquirers shall support decoding and payment request submission to UPI system;

4. Transaction types supported shall include Purchase, Void, Refund, and Message Result Inquiry;

5. Acquirer shall support sending transaction result notification to merchants.

6.Acquirer will connect to UPI system which supports single-message transaction only through API.

7.For encoding specification of consumer-presented and merchant-presented code, please refer to 'Consumer-presented QR Code'and 'Merchant-presented QR Code' column.

8.For sample message of each interface, you will find them in each API's sample code column and a package of all sample message in the 'Documentation' column


Flow Chart
Flow Chart


Consumer-Presented.jpg

Merchant-presented.jpg
API Reference
API Reference
  • PURCHASE
  • VOID
  • REFUND
  • MSG_RESULT_INQUIRY
  • MPQRC_VERIFICATION
  • TRX_STATUS_NOTIFICATION
Interface description
This interface is used to realize the QRC purchase transaction for Consumer-Presented case.
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 Valid Value: "1.0.0"
Message ID msgID AN 29 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the Acquirer initiates on any day. The value in the response must match the value in the request.Components: “Q”+ Acquirer IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits).Example:Q0001034420171230235959000000
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request.Example:20170714235959 Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "PURCHASE".Example:PURCHASE
Acquirer IIN acquirerIIN AN 8 M:Mandatory The distinctive value associated to the Acquirer. Example:00010344
Transaction Information trxInfo object M:Mandatory
Card Information Capture Method captureMethod ANS 1-64 M:Mandatory Valid Values: "CONSUMER_PRESENTED_QRC",Reserved Values:"NFC" "STORED_CREDENTIALS" "MANUAL" "CONTACT" "MAGSTRIPE" "UNKNOWN"
Consumer presented QR Code Payload cpqrcPayload ANS 1-320 C:Conditional Present if it is a consumer-presented QRC transaction.It contains the raw payload data.
Primary Account Number pan AN 1-2048 M:Mandatory Encrypted with the public key of the Encryption Certificate. The "pan" can be the card number or a token representing the Cardholder account. Example:Encrypted value of "6211110000000000000"
Transaction Amount trxAmt ANS 1-13 M:Mandatory The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark.When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals.The following are examples of valid Transaction Amounts: "98.73", "98" and "98.".
Transaction Currency trxCurrency N 3 M:Mandatory A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist.Example:156
Transaction Fee Amount trxFeeAmt ANS 1-13 C:Conditional Present if the Tip or Convenience Fee exists.The tip or the convenience fee.Example:1.10
Coupon Information couponInfo ANS 1-30 O:Optional
Merchant ID merchantID AN 1-15 M:Mandatory The distinctive value associated to the Merchant. The value must uniquely identify any Merchant of the Acquirer.Example:ABCDE01
Merchant Category Code mcc N 4 M:Mandatory Convenience store is represented by "5411".
Merchant Country Code merchantCountry N 3 M:Mandatory 156
Merchant Name merchantName ANS 1-25 M:Mandatory "UnionPay International"
Merchant City merchantCity ANS 1-12 M:Mandatory The distinctive value associated to the terminal. Example:“abcde01”
Terminal ID terminalID ANS 1-8 M:Mandatory The distinctive value associated to the terminal.
Certificate and Signature certificateSignature object M:Mandatory
Acquirer Signature Certificate ID acquirerSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The Acquirer uses the private key of this certificate for signature.
UAIS Encryption Certificate ID uaisEncCertID AN 1-128 C:Conditional The serial number of the certificate. The Acquirer system uses the public key of this certificate for encryption.
Signature signature ANS 1-2048 M:Mandatory 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 29 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the Acquirer initiates on any day. The value in the response must match the value in the request.Components: “Q”+ Acquirer IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits).Example:"Q0001034420171230235959000000"
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request.Example:"20170714235959" Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "PURCHASE".Example:“PURCHASE"
Acquirer IIN acquirerIIN AN 8 M:Mandatory The distinctive value associated to the Acquirer. Example:"00010344"
Transaction Information trxInfo object M:Mandatory
Primary Account Number pan AN 1-2048 M:Mandatory Encrypted with the public key of the Encryption Certificate. The "pan" can be the card number or a token representing the Cardholder account. Example:Encrypted value of "6211110000000000000"
Transaction Amount trxAmt ANS 1-13 M:Mandatory The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705".
Transaction Currency trxCurrency N 3 M:Mandatory A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist.Example:"156"
Discount discount ANS 1-13 O:Optional The amount of discount. The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals.Example:"1.10"
Cost Amount costAmount ANS 1-13 O:Optional The cost amount after the discount, indicating the amount the Cardholder actually pays for the transaction when a promotion is involved. The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals.Example:“100.00”　
QRC Voucher Number qrcVoucherNo ANS 1-20 C:Conditional Example:"1234567890123456789"
Retrieval Reference Number retrievalReferenceNumber AN 12 C:Conditional Populated by UnionPay if the payment is approved.
Settlement Date settlementDate N 4 C:Conditional Example:"1230" Format: MMDD
Settlement Currency settlementCurrency N 3 C:Conditional A 3-digit numeric value, as defined by [ISO 4217], that indicates acquirer’s settlement currency. Example:“840”
Settlement Amount settlementAmt ANS 1-13 C:Conditional The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals.Example:“15.17”
Settlement Conversion Rate settlementConvRate ANS 1-9 C:Conditional Example:"0.15000"
Cardholder Billing Currency cardholderBillingCurrency N 3 C:Conditional A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Example:“840”
Cardholder Billing Amount cardholderBillingAmt ANS 1-13 C:Conditional The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals.Example:“15.17”
Cardholder Billing Conversion Rate cardholderBillingConvRate ANS 1-9 C:Conditional Example:"0.15000"
Conversion Date conversionDate N 4 C:Conditional Example:"1230" Format: MMDD
Message Response msgResponse object M:Mandatory
Response Code responseCode AN 2 M:Mandatory It contains a code that defines the response to a request. Refer to the Response Code and Message for the valid values.Example:"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 by the Merchant to notify the consumer of the payment outcome. Refer to the Response Code and Message for details.Example:"Approved"
Certificate and Signature certificateSignature object M:Mandatory
UAIS Signature Certificate ID uaisSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The UAIS system uses the private key of this certificate for signature.
Acquirer Encryption Certificate ID acquirerEncCertID AN 1-128 C:Conditional The serial number of the certificate. The UAIS system uses the public key of this certificate for encryption.
Signature signature ANS 1-2048 M:Mandatory Refer to the Signature for details.
Sample code
Request code
Java Other 
public class UPIInterfaceRequest {	
    private static String URL = "https://uaistest.unionpayintl.com/uais";	
    private static String CONTENT_TYPE = "application/json"; 
    private static String USER_AGENT = "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.99 Safari/537.36";	
    public static void main(String[] args) {		
        //Assemble the transaction message.		
        TranData tranData = getKeyInquiryExchange();		
        //Data Encryption		
        String pan = tranData.getTrxInfo().get("pan");
        String encPan = encryptByPublicKey(pan.getBytes("UTF-8"),publicKey);
	tranData.getTrxInfo().put("pan", encPan);
	String jString = JSON.toJSONString(tranData);		
	//Obtain a signed message.		
	String signString = addSign(jString);		
	//Get the HTTP response		
	String resString = sendPost(URL, jString);		
	//signature verification		
	verifySign(resString,publicKey);		
	//Data Decryption		
	tranData = JSON.parseObject(resString,TranData.class);
	pan = decryptByPrivateKey(Base64Utils.decode(tranData.getTrxInfo().get("pan")), privateKey);
    }	
	
    //Send an HTTP request	
    public static String sendPost(String url, String bodyParams) {        try {
        HttpResponse<String> response = Unirest.post(url)
                    .header("User-Agent", USER_AGENT)
                    .header("Content-Type", CONTENT_TYPE)
                    .body(bodyParams)
                    .asString();           
            return response.getBody();
        } catch (UnirestException e) {
        	e.printStackTrace();
            System.out.println("HTTP Get Error:{}");
        }        return "";
    }	
	
    //Assemble the transaction message	
    public static TranData getKeyInquiryExchange() {
	TranData tranData = new TranData();
	MsgInfo msgInfo = new MsgInfo();
	HashMap<String, Object> trxInfo = new HashMap<String, Object>();
	HashMap<String, Object> certificateSignature = new HashMap<String, Object>();
	String msgType = "KEY_INQUIRY_EXCHANGE";
	String timeStamp = "20180131170300";
	String versionNo = "1.0.0";
	String acquireIIN = "47030344";
	String msgID = StringUtil.getMsgID(acquireIIN);
	String uaisSignCertID = "1111111111";
	String uaisEncCertID = "1111111111";
	msgInfo.setMsgID(msgID);
	msgInfo.setMsgType(msgType);
	msgInfo.setTimeStamp(timeStamp);
	msgInfo.setVersionNo(versionNo);
	msgInfo.setAcquirerIIN(acquireIIN);
	trxInfo.put("uaisSignCertID", uaisSignCertID);
	trxInfo.put("uaisEncCertID", uaisEncCertID);
	certificateSignature.put("acquirerSignCertID", "180328105101");
	certificateSignature.put("signature", "00000000");
	tranData.setMsgInfo(msgInfo);
	tranData.setTrxInfo(trxInfo);
	tranData.setCertificateSignature(certificateSignature);
	String str = JSON.toJSONString(tranData);		
	return tranData;
    }	
	
    /**
    * Signature verification
    * @param data
    * @param publicKey
    * @param sign
    * @return
    * @throws Exception
    */
    private static boolean verifyUais(byte[] data, String publicKey, String sign) throws Exception {
	MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
	messageDigest.update(data);		
	byte[] hashData = messageDigest.digest();		
	byte[] keyBytes = Base64Utils.decode(publicKey);
	X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
	KeyFactory keyFactory = KeyFactory.getInstance("RSA");
	PublicKey publicK = keyFactory.generatePublic(keySpec);
	Signature signature = Signature.getInstance("NONEWithRSA");
	signature.initVerify(publicK);
	signature.update(hashData);		
	return signature.verify(Base64Utils.decode(sign));
    }	
	
	
    /**
    * Encrypted with the public key
    * @param data
    * @param publicKey
    * @return
    * @throws Exception
    */
    private static String encryptByPublicKey(byte[] data, String publicKey) throws Exception {		
        byte[] keyBytes = Base64Utils.decode(publicKey);
        X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(keyBytes);
	KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
	Key publicK = keyFactory.generatePublic(x509KeySpec);
	Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
	cipher.init(Cipher.ENCRYPT_MODE, publicK);		
	int inputLen = data.length;
	ByteArrayOutputStream out = new ByteArrayOutputStream();	int offSet = 0;		
	byte[] cache;		
	int i = 0;		
	while (inputLen - offSet > 0) {			
	    if (inputLen - offSet > MAX_ENCRYPT_BLOCK) {
		cache = cipher.doFinal(data, offSet, MAX_ENCRYPT_BLOCK);
	    } else {
		cache = cipher.doFinal(data, offSet, inputLen - offSet);
	    }
	    out.write(cache, 0, cache.length);
	    i++;
	    offSet = i * MAX_ENCRYPT_BLOCK;
	}		
	byte[] encryptedData = out.toByteArray();
	out.close();		
	return Base64Utils.encode(encryptedData);
	}
	
    	
    /**
    * Decrypted only with the private key
    * @param encryptedData
    * @param privateKey
    * @return
    * @throws Exception
    */
    private static String decryptByPrivateKey(byte[] encryptedData, String privateKey) throws Exception {		
        byte[] keyBytes = Base64Utils.decode(privateKey);
	PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
	KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
	Key privateK = keyFactory.generatePrivate(pkcs8KeySpec);
	Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
	cipher.init(Cipher.DECRYPT_MODE, privateK);		
	int inputLen = encryptedData.length;
	ByteArrayOutputStream out = new ByteArrayOutputStream();	int offSet = 0;		
	byte[] cache;		
	int i = 0;		
	while (inputLen - offSet > 0) {			
	    if (inputLen - offSet > MAX_DECRYPT_BLOCK) {
		cache = cipher.doFinal(encryptedData, offSet, MAX_DECRYPT_BLOCK);
	    } else {
		cache = cipher.doFinal(encryptedData, offSet, inputLen - offSet);
	    }
	    out.write(cache, 0, cache.length);
	    i++;
	    offSet = i * MAX_DECRYPT_BLOCK;
	}		
	byte[] decryptedData = out.toByteArray();
	out.close();	
	return Base64Utils.encode(decryptedData);
    }
}
Response code
Other

{  
   "msgInfo":{  
      "acquirerIIN":"27200704",
      "msgID":"Q2720070420180418210404552567",
      "msgType":"PURCHASE",
      "timeStamp":"20180409181042",
      "versionNo":"1.0.0"
   },
   "trxInfo":{  
      "msgHead":"303130202020202020202020696E636F6D32202020203137322E31392E3138342E33362020B1F0D8D8620100002020202020202020202020202020202020202020202020202020202020202020202020",
      "trxCurrency":"840",
      "qrcVoucherNo":"18041821070392008014",
      "retrievalReferenceNumber":"041821070496",
      "settlementDate":"0418",
      "pan":"JPN33h9+DoKQ4zz7KjCkf2ha9MD6FuAGq1HCZokCQzn+oO+ZBfkOEevTL6g/bsmXJmsk/xKd8fMrj63qhDWT60uF51Bf9mBj1G7bWTkIbiWi47B40lolZd3CnlGJY4aAHEKr2TO//zEaT+p5NxMxCdK7dJ+unYE0HiB08LxJ7irb6OuDL9PWh71a+53Zu+sg2cQ2tamZhRo9OWAHu6VOZ9P++wrcRLEYDVHtsu9sDLc+gsIjjrqzvh5vOuewBRvGWrdkr3xH/o4ZauSFWScaPu9+lqnLzbD/byCb5mdRAOQFoKD+m+3CYuaZRbV+eVknGUlxhb1/A2Jr0bzrL32Rkg==",
      "trxAmt":"10.00"
   },
   "msgResponse":{  
      "responseCode":"00",
      "responseMsg":"Approved"
   },
   "certificateSignature":{  
      "signature":"jZGdSlGdneeRAJlHFXcYc4q6CctVgn7GaRxe1zEdxoB2NKFm5jnLCRP8mvtNUTOuD8OO4IQ3TkNasWpe2dcBTr24t8mBojksz3mUEYEC00hiv7xfDyCWFV6mWeXl99r2uGx5LjykmcvoCDwkvZXz14ol3K8MeDl9lw7fnXobHMaenTLfBFPh+n1gPnP/27vo75NQa5d0eDPfcd3iqMs9y3hzQ2ltDPjCbXEs1zpV06kXQxg5DJPKxOHyL3zVUfVEPUNqQuc6n78U4ga4M8hvARRXFkDqjoxFucZanb/1nMcBuPZQVI+/Ic8Wk/dBzuJy3DjG8QkqVjnPfbcHzqRkSg==",
      "uaisSignCertID":"180328105101",
      "acquirerEncCertID":"180328105101"
   }
}

Sequence Chart
Sequence Chart

A.Purchase (Merchant-Presented)

 purchase (merchant-presented)-新.png


1.Merchant requests an EMV QR Code from the Acquirer.  

2.The Acquirer generates the EMV QR Code and returns to the merchant. 

Note: the QR code requested by merchants can be either a long-term static QR code or a one-time dynamic QR code. 

3.Cardholder scans the QR Code showed by the merchant via their App, which then parses the QR Code to obtain the relevant information of merchant (including elements such as the merchant ID, merchant name, merchant type, merchant location, transaction amount, transaction currency and country code) and initiates a payment request to the UnionPay system. 

Note: For a static QR Code payment, if the transaction amount is not included in the QR Code then the cardholder will need to type the payment amount into the App and confirm to pay. For a dynamic QR Code payment, the card holder will not need to type the payment amount into the App but they will need to confirm the payment (need to type in their CDCVM or PIN into the App).

4.UnionPay System initates the transacation verification to the Accquirer . 

Note: QRC voucher number refers to a string of numbers as the transaction voucher number that is generated by UnionPay system. It can be obtained by the cardholder in the App transaction notification, and included in the transaction notification to merchant as well. The QRC voucher number is unique and is used for subsequent transaction processing.

5.The Acquirer checks the validity of merchant information. If merchant info. is NOT valid, the Acquiring system will return a payment response to UnionPay System and rejects the transaction. UnionPay System then sends a rejected payment result response to the App Gateway, and the App Gateway sends the rejection result notification to the App. 

6.The Acquirer checks the validity of the merchant information. If merchant info. IS valid, the Acquiring system will return a payment reponse to UnionPay System and confirm the transaction. 

7.UnionPay System transfers the payment request (including QRC voucher number) and sends to the Issuer for authorization and obtain the corresponding payment response. 

8.If the transaction is successful, UnionPay System returns a transaction result notification to Acquirer, and then the Acquirer sends the transaction result notification to the merchant. 

9.UnionPay System sends the transaction result notificaiton to the App Gateway, including the QRC voucher number. The App Gateway sends the payment result response to the cardholder App, including the QRC voucher number. 

Notice:

1.If the UnionPay System system does not receive the response of transaction notification from Acquirer within 10s, it will reject the merchant-presented QRC purchase request from the App Gateway and send the transaction notification to the Acquirer with the rejected status.

2.If the UnionPay System does not receive the transaction notification response from the Acquirer within 10s, it will store and forward transaction notification request message.


B.Purchase (Consumer-Presented)

  purchase (consumer-presented)-新.png

1.Cardholder requests an EMV QR Code from UnionPay System and displays the QR Code with App. 

2.After scanning the QR Code, the merchant submits a payment request to Acquirer, and Acquirer initiates the payment request to UnionPay System.

3.UnionPay system will verify the transaction information including the QR Code; if the verification is approved, UnionPay system may, depending on the QR Code transaction requirement set by App, choose to trigger an additional processing request to cardholder, then App verifies the identity of cardholder and cardholder confirms to submit payment. 

4.If additional processing fails, UnionPay system will directly respond to Acquirer; if the previous step successds, UnionPay system will continue initiating an authorization request to the issuer;. 

5.After receiving the success response, UnionPay system returns a purchase response to the Acquirer (may choose to return the QRC payment voucher number  (F125) according to the situation of the acquirer); 

6.Meanwhile, UnionPay system sends a transaction notiofication to cardholder. 

7.The transaction is successfully completed and the merchant prints the transaction receipt according to the cardholder's request, signature will not be required. 

Notice:

1.When Acquirer does not receive the PURCHASE response message within 45 seconds, it can initiate a message result inquiry, using the Message ID of the PUECHASE massage to check if the payment is successful.

2.UnionPay System will return the PURCHASE transaction outcome (approved/rejected/pending) and settlement information to the Acquirer.


C.Cancellation 

 Cancellation-新.png


1.Merchant initiates a CANCELATION request to the Acquirer through using the QRC voucher number.

2.Under Merchant-Presented Mode, the Acquirer matches the transaction according to QRC voucher number and initiates an cancelation request to UnionPay System;

Under Consumer-Presented Mode, the Acquirer uses the Message ID of PURCHASE to void the consumer-presented QRC purchase.

3.UnionPay System sends the canelation request to the Issuer.

4.The Issuer sends the cancelation response to UnionPay System. 

5.UnionPay System sends the cancelation response to the Acquirer, and the Acquiring system returns the cancelation notification to the merchant.

6.UnionPay System sends the CANCELATION notification to the App through App Gateway. 


D.Refund 

 refund-新.png


1.Merchant initiates a REFUND notification to the Acquirer using the QRC voucher number.

2.The Acquirer matches the transaction with the QRC voucher number and submits a refund request to UnionPay System. 

3.UnionPay System immediately responds to the Acquirer with a refund response, and the Acquirer sends the refund notification to merchants.

4.UnionPay System sends a refund notification to the Issuer.

5.UnionPay System sends a refund notificaiton to the App Gateway, and the App gateway sends a refund notification to the App. 
Security Requirement
Security Requirement

Signature

Signature is used to validate the integrity and authenticity of the message. The Acquirer shall follow the steps below to generate a signature or verify the signature: 

To sign a message:

1.To-Be-Signed String: Prepare the message to be sent to the UAIS system in the JSON format. Fill the “signature” with “00000000”. Messages shall contain no white space between fields.

2.Use the SHA256WithRSA algorithm and the private key of Acquirer Signature Certificate to calculate the signature from the To-Be-Signed String.

3.Base64 encode the signature from step 2 and put it as the value of “signature”. The Base64 encoding and decoding are defined in [RFC 4648].

To verify a message:

1.To-Be-Signed String: Prepare the message received from the UAIS system in the JSON format. Fill the “signature” with “00000000”. Messages shall contain no white space between fields.

2.Base64 decode the value of “signature” to get the signature from the sender.

3.Use the SHA256WithRSA algorithm and the public key of UAIS Signature Certificate with the To-Be-Signed String to verify the signature.


Encryption

For sensitive information such as Cardholder Verification Information (“cvmInfo”), Primary Account Number (“pan”), etc., the UAIS requires to encrypt its value before transmitting it in the message. The Acquirer shall follow the steps below: 

To encrypt a data element:

1.Use the public key of UAIS Encryption Certificate and encrypt a data element with RSA (PKCS1_PADDING) algorithm.

2.Base64 encode the encrypted result and fill it in the value of the field.

To decrypt a data element:

1.Base64 decode the value of the field.

2.Use the private key of Acquirer Encryption Certificate and decrypt the result of step1 with RSA (PKCS1_PADDING) algorithm.

Examples:

Original message

“cvmInfo”:{"expiryDate":"12/22", "cvn2":"123", "mobileNo":"123456789100"}

Data source to be encrypted: {"expiryDate":"12/22", "cvn2":"123", "mobileNo":"123456789100"}

1.Use the UAIS public key of Acquirer Encryption Certificate (key length: 2048 bits) and encrypt the data source with RSA algorithm. (Shown in Hex representation)

79849DE774CC392C238BB8B3C4432744CCFACD880AEA1455B28E15A3A211B0EDC2BA9F7E468F981D846D6F1C411EBDCF4F193AC0EAF068D28B592D0683AB39B8235F263050F623E47491AA372705173E4424EA2781C450B672DFF71A19BA8175C6A1E70A593960DBBDFE0F5DE5E2A233C5B3A9626C7062D7BAD27C781E1ACFC9E7C2BF72494FAA337928A42F9762B5C1641E7F39FCBE4D54EA79AA09579FB9EF5ECC1057B4C0C27B64E5D14965A1236C706F718A948402553122B4E71A4AAD406948199C24302BE535E1C8949BF7D8CF0456A2694FCCDF29D3D277BDFA5B500575260C6C28120D2BA0CBBA416BDB861623BD2E28EE6C6A4B9FA5F24B1B7D2F9B

2.Base64 encode the encrypted result.

eYSd53TMOSwji7izxEMnRMz6zYgK6hRVso4Vo6IRsO3Cup9+Ro+YHYRtbxxBHr3PTxk6wOrwaNKLWS0Gg6s5uCNfJjBQ9iPkdJGqNycFFz5EJOongcRQtnLf9xoZuoF1xqHnClk5YNu9/g9d5eKiM8WzqWJscGLXutJ8eB4az8nnwr9ySU+qM3kopC+XYrXBZB5/Ofy+TVTqeaoJV5+5717MEFe0wMJ7ZOXRSWWhI2xwb3GKlIQCVTEitOcaSq1AaUgZnCQwK+U14ciUm/fYzwRWomlPzN8p09J3vfpbUAV1JgxsKBINK6DLukFr24YWI70uKO5sakufpfJLG30vmw==

3.Fill it in the value of the field.

“cvmInfo”: “eYSd53TMOSwji7izxEMnRMz6zYgK6hRVso4Vo6IRsO3Cup9+Ro+YHYRtbxxBHr3PTxk6wOrwaNKLWS0Gg6s5uCNfJjBQ9iPkdJGqNycFFz5EJOongcRQtnLf9xoZuoF1xqHnClk5YNu9/g9d5eKiM8WzqWJscGLXutJ8eB4az8nnwr9ySU+qM3kopC+XYrXBZB5/Ofy+TVTqeaoJV5+5717MEFe0wMJ7ZOXRSWWhI2xwb3GKlIQCVTEitOcaSq1AaUgZnCQwK+U14ciUm/fYzwRWomlPzN8p09J3vfpbUAV1JgxsKBINK6DLukFr24YWI70uKO5sakufpfJLG30vmw==”


Consumer-presented QR Code
Consumer-presented QR Code

The QR Code has the same structure as the EMVCo QRC does. 1 Application Template is shown below.

E_个人码-模板_1.png
Merchant-presented QR Code
Merchant-presented QR Code


Please refer to Merchant Presented QR Code Encoding Specification
Successful Case
Successful Case

2. 威富通-QR code acceptance.png
Steps to Launch
Steps to Launch

Step 1 - QR Code Self-Test

Developers shall check and test if the acquirer system can generate QR Code compliant with UPI Standard, or parse the UPI QR Code from Consumer App.


1) For Merchant-Presented QR Code Acquirer, developers shall test if the QR Code is generated following UPI Technical Specification, and can be scanned and processed by mobile wallet (Consumer App) supported UPI QR Code.

The testing Consumer App can be obtained from testing support team or QR Code Self-Test Platform"

 

2) For Consumer-Presented QR Code Acquirer, developers shall test if the acquirer system can recognize and decode the QR Code generated by mobile wallet (Consumer App) supported UPI QR Code.

The testing Consumer QR Code can be obtained from testing support team or QR Code Self-Test Platform."

    

Step 2 - Public Key Management

Developers need to exchange certificate of encryption & signature (Acquirer Encryption Certificate ID, Acquirer Encryption Public Key, Acquirer Signature Certificate ID and Acquirer Signature Public Key) before requesting payment transaction.

 

1) The first time exchange shall be operated manually between Developers and UPI Technology specialist considering security. 

Note: Developers could use Acquirer IIN 47030344 to test, which does not need signature and encryption process.


2) The Acquirer shall submit a KEY_INQUIRY_EXCHANGE request message to the UAIS system at least once per day.


3) If the UAIS returns the new UAIS Signature Certificate ID or new UAIS Encryption Certificate ID, the Acquirer shall add in its system the new UAIS Signature Certificate ID and new UAIS Signature Public Key, or the new UAIS Encryption Certificate ID and new UAIS Encryption Public Key and send the KEY_RESET_RESULT request to the UAIS.

 

Note:

1) During the Public Key Management process, the UAIS and Acquirer shall both use the old Signature Certificate ID and old Signature Public Key for “Signature” in the request and response messages of KEY_INQUIRY_EXCHANGE and KEY_RESET_RESULT. The new Signature Certificate ID and new Signature Public Key shall be enabled after the Public Key Management processing.


2) Once an encryption public key or a signature public key is updated successfully, both the UAIS and the Acquirer shall reserve the old key and the new key for at least 7 days in their systems. After 7 days, the systems can remove the old key only if the new key is successfully used for one message."

    

Step 3 - Online Test and Operation Process

Developers shall submit the testing application to UPI UTSS for online testing and proceed following standardized operation process.
FAQ and Documentation
FAQ and Documentation
FAQS:
  • Q ：
    Why do I need to fill the 'signature' with '00000000'?
    A ：

    By verifying the signature, the message receiver needs to verify the full message except for the field 'signature' itself, so 'signature' in the to-be-signed string needs to be replaced by a fixed value '00000000'.

  • Q ：
    Everytime when I'm fetching the public key from the certificate. it returns a different value of public key. Is this valid?
    A ：

    Getting the public key from the certificate should be a fixed value.

  • Q ：
    Is the public key fetched from any certificate file or is it shared from developer?
    A ：

    The public key from the program comes from certificate,  the first and last lines are removed, and the newline character is removed.

  • Q ：
    Failed to decrypt the message returned by the UPI system.
    A ：

    The ciphertext input to the decryption function must be a byte array:

    public static String decryptByPrivateKey(String encryptedDataString, String privateKey) throws Exception {
byte[] encryptedData = Base64Utils.decode(encryptedDataString.getBytes());//Please pay attention to this line
//byte[] encryptedData = encryptedDataString.getBytes();
byte[] keyBytes = Base64Utils.decode(privateKey.getBytes());
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
Key privateK = keyFactory.generatePrivate(pkcs8KeySpec);
Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
cipher.init(Cipher.DECRYPT_MODE, privateK);
int inputLen = encryptedData.length;
ByteArrayOutputStream out = new ByteArrayOutputStream();
int offSet = 0;
byte[] cache;
int i = 0;
while (inputLen - offSet > 0) {
if (inputLen - offSet > MAX_DECRYPT_BLOCK) {
cache = cipher.doFinal(encryptedData, offSet, MAX_DECRYPT_BLOCK);
} else {
cache = cipher.doFinal(encryptedData, offSet, inputLen - offSet);
}
out.write(cache, 0, cache.length);
i++;
offSet = i * MAX_DECRYPT_BLOCK;
}
byte[] decryptedData = out.toByteArray();
out.close();
return new String(decryptedData);
}


  • Q ：
    Failed to extract the public key from the public key certificate
    A ：

    Check to see if the certificate is formatted correctly. Make sure the certificate is padded with

    -----BEGIN CERTIFICATE-----

    and 

    -----END CERTIFICATE-----

    lines


  • Q ：
    I always got 'Signature verification fails' error.
    A ：

    There are many reasons for UPI System return "Signature verification fails.".The following common causes of errors are for reference: 

    1. Messages shall contain no white space or newline between fields. Because of the message must ensure no changes during transmission and processing, so no white space between field and field or order adjustment is allowed. 

    2. Use the hash value as a byte array to calculate the SHA256 signature.Please make sure that your signature function supports input param as a byte array.


  • Q ：
    How to learn signature and encryption process?
    A ：

    Developer shall use Acquirer IIN 47030344 in sandbox test, which does not need signature and encryption process. Later when you are ready to go live, we will provide you with complete documentation.

  • Q ：
    Are all currencies supported?
    A ：

    We support all currenies transaction, which can be configured under certain Acquirer. For testing acquirer given in sandbox testing, only '156' currency is supported. Please use 156 currency code to test, or you will recieve 'Message Format Error'

  • Q ：
    Unauthorized Access Error
    A ：

    Please check whether the 'acquirerIIN' is 47030344. This IIN does not require developers to encrypt and sign request message.Currently, other IIN is not supported.

  • Q ：
    Time Requirements for transactions of 'Void' and 'Refund'
    A ：

    'Void' supports trasactions happened in that day, and 'Refund' supports trasactions happened in one year.

Documents:
Response Code Reference
Response Code Reference
Response code Description
00 Approved
01 Please refer to the card issuer
03 Invalid merchant
04 Pending. Transaction result is unknown. Please check later.
05 Cardholder verification fails.
12 Invalid transaction
13 Invalid amount
14 Invalid card number
15 No such issuer
20 Duplicated QRC transaction and expired QRC
21 Card status error
25 Unable to locate the original transaction
30 Message format error
34 Fraud card
40 The transaction is not supported by the issuer. Cross-border QRC transaction is not applicable for the card
41 Lost card
43 Stolen card
51 Insufficient balance
54 Expired card.
55 User input invalid PIN or didn’t input PIN
57 Transaction not permitted to cardholder or QRC transaction is not applicable for the card
61 The transaction amount exceeds issuer’s limit on crossborder QRC transaction limit
62 Restricted transaction
90 The system is in cut-off.
91 Issuer system error
92 Network error
94 Duplicated transaction
96 UnionPay system error
98 Timeout
A0 Signature verification fails.
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2021. All rights reserved