UnionPay International Developer

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

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=="}}

Interface description

The mobile application will download and display the Terms and Conditions for the cardholder to accept or decline. If the TNC is declined, the enrollment process will terminate. Otherwise, the mobile application will capture the Cardholder Verification Information that was requested from the UPI, and send them in the ACCOUNT_VERIFICATION request.

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	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 "A0001034420171230235959000012"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss.
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "ACCOUNT_VERIFICATION"
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

M:Mandatory

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 Information

cvmInfo

object

M:Mandatory

Encrypted with the public key of the Encryption Certificate.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". Note 1: The "idType" and "idNo" shall be present together.Note 2: If no CV method is required, the object shall be "cvmInfo": {} Encrypted value of{"expiryDate":"12/22", "cvn2":"123", "mobileNo":"86-123456789100"}

Expiry Date	expiryDate	AN	4	C:Conditional	Format: MM/YY
CVN2	cvn2	N		C:Conditional
NAME	name	S		C:Conditional
ID Type	idType	ANS		C:Conditional
ID Number	idNo	AN		C:Conditional
Mobile Number	mobileNo	ANS		C:Conditional

Authentification Value

authenticationValue

ANS

1-2048

O:Optional

The authentication value can be passed to the issuer for validation.

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	1-128	C:Conditional	Present if encrypted information exists in the request message. The serial number of the certificate. The application 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 "A0001034420171230235959000013"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss.
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "SENDING_OTP"
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	M:Mandatory	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, and TOKEN_PROVISIONING. The value must be unique for each enrollment process.
OTP Method	otpMethod	array	1	C:Conditional	List of OTP Methods. An array of string separated by comma on the list of OTP methods supported by the issuer. The application shall display all allowed methods to the consumer, and the consumer will select one. If this data element is not sent, then mobile application DOES NOT need to process any OTP. Valid Values： "1"： OTP is required through SMS; "2"： OTP is required through Email; "3"： OTP is required through call center; "4"： OTP is required through web.

Message Response

msgResponse

object

M:Mandatory

	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"
	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"

Certificate and Signature

certificateSignature

object

M:Mandatory

Sample code

Request code

Other

{"msgInfo":{"versionNo":"1.0.0","msgID":"20200415144747004943","timeStamp":"20200415144747","msgType":"ACCOUNT_VERIFICATION","walletID":"39990004"},"trxInfo":{"deviceID":"28e5846283dc4b768814d485ff5a401d","enrolID":"216807","cvmInfo":"Q6+G3p3LDf2axZ7umvrO2/YFl7TFET2QcXpGCWM1n6VgQKsj6AkuHscabN2JjbfU9bQVvNGKAoP2h73kzMATzmVbb5mCTY2uQB01j1ixFG2ocIwlpP5if3JUwbDi4SScFi9ui5qEuT4+qU2gTF7NmTIEWRHNSmFZeKWIcEnMD7/s4ZhV7ioCQjdO+HnSCr6NbIeyEcpR6CPrTyZyw2k+yOJodL+rjNOIoqLdmNix6zn5qlYD95KmFD4NJal84OFM3qtx3xBn9WpT8PZIZKccm03+9la0YZ/WN8ESAJ50ZQPU6eG8Qhs4+7/8Lwh2Cb4JD5PDETJxn0xR5oINb2zZXA=="},"certificateSignature":{"appSignCertID":"1509455488","umpsEncCertID":"1508413608","signature":"LYSZ8Ni06mQbN9QZSS/aeIi9UQ08z+MemZkygDUDtnmHMp7Ny1QoRsPiHyAe9f27mR+5a4M0T4dygc7uA1k39/OfCD8tBd0kGrR/vysNj88WOsg129tOeGTmepHmfpo+lbJtiBgx7AhhuWXixpEbeP4X5ur4OPl8m4L7/Lhs6VP3ZFep9j0zh09tTvk1MY7YudeVH0eaOMv5KA1b2nZgkiEelQgzZCCd9YYneeT+TOG3iV6Ao6aEaZ0Nkl78j/gL35g5+sOoWa5b9bzno0ZK9iqsZeIBbU3cblVm6Yt+bn8L9OERES7geh45sTBxSgssl8RysmRaLXoJikDVclgFng=="}}

Response code

Other

{"trxInfo":{"deviceID":"28e5846283dc4b768814d485ff5a401d","enrolID":"216807","otpMethod":["1"]},"msgInfo":{"versionNo":"1.0.0","msgType":"ACCOUNT_VERIFICATION","msgID":"20200415144747004943","timeStamp":"20200415144747","walletID":"39990004"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"NscyrQxAcplB+mNqVl7yZoIbVtWRR80x+B7F/JPLLqz5kvTsoEKGL7n1EZNl1afInZj+i6SFAjgTZ8Jau+1B1JR+wq9WH8kNGHrz87NR/DJtdCWQUjYTuKuD7INykVx29gh4EXzy4BvcxTCF73qXd9I57ZKu1VMe2ph8Hw9KWeagK41ii8S+KkkO7vgK5lDgOe4xIdq3UJE/JR2/y58rbDVVW5N78/zJHjXbDWBRJ41VFzz7SAyKZKn8p9j+IoW8iGsR7fIqmf5ratrvwUUr+VFw1nN4p9mFmcaYIzQOcFdzfdpJ2aBiHSlO4e3UkWg34rkpTYARF5nNXTRdzIjJMA=="}}

Interface description

The mobile application will display the allowed methods to the cardholder. After the cardholder chooses one, the mobile application will send SENDING_OTP message to the UPI, and the Issuer, or a processor on behalf of the Issuer, will send an OTP to the mobile phone number of the cardholder. The UPI will return the OTP length, expiry time, and maximum attempt number in the response message. If the cardholder does not receive the OTP, the application can send another SENDING_OTP message 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	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 "A0001034420171230235959000013"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "SENDING_OTP".
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	M:Mandatory	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, and TOKEN_PROVISIONING. The value must be unique for each enrollment process.
Supported OTP Method	supportedOtpMethod	N	1	M:Mandatory	Valid Values： "1"： OTP is required through SMS; "2"： OTP is required through Email; "3"： OTP is required through call center; "4"： OTP is required through web.

Certificate and Signature

certificateSignature

object

M:Mandatory

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 "A0001034420171230235959000014"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "SENDING_OTP".
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
Enrollment ID	enrolID	N	16	M:Mandatory	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. "0000000000000009"
Supported OTP Method	supportedOtpMethod	N	1	C:Conditional	Valid Values："1"： OTP is required through SMS,"2"： OTP is required through Email, "3"： OTP is required through call center,"4"： OTP is required through web "1"
OTP Length	otpLength	N	1	C:Conditional	The length of the OTP "6"
OTP Expiry	otpExpriy	N	3	C:Conditional	When the value is "60", it indicates that the OTP will expire after 60 seconds. "60"
OTP Maximum Attempt Number	otpMaxAttempt	N	1	C:Conditional	The maximum number of allowed invalid attempts of the OTP. The UMPS will reject the following SENDING_OTP message, when the number of attempts reaches this value. "3"

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

Sample code

Request code

Other

{"trxInfo":{"deviceID":"A3B52F8564AB42073F8CBC94568D3F3A7706E5274C650DDC76AC1C34642E3F54","enrolID":"216613","supportedOtpMethod":"1"},"msgInfo":{"versionNo":"1.0.0","msgType":"SENDING_OTP","msgID":"A00010344200414051817000011","timeStamp":"20200414051817","walletID":"00000001"},"certificateSignature":{"appSignCertID":"201806211822","signature":"fEX86ugiA6fZQQ9TaTaV8ghnHCzSC2tNmA/9+Ma5+dcy5JrFZN/TmkGUx2ZL6M7MdPHolJFQQrlC0EcGDkwkjS9MUrJ1ioiGwzA++bvDR+2mdiqM8Dh9PKdjny3hYvXakcUxcO7IRAlFmUdKebN+9qt8ppEt/Ex74YWCyHl0r41a2R1x3f2I/semBSjYYUs4LQTJpuwvTQ5EPRs4yu3syjwcTekWRJGG1jIfdhL1x/1aMZ7T523NTWYOxdezTj+I5RHvS9LO/UlVKX6RQjUmtiJ4MrglYJkK0o/UeTiTIZPZfkndROdZob5br52ru3C4d/Yyj9d7fJPijwoJ6bicGkVwIUXgzvnWb+4Mt9r3Kbi5jiRaV2wxtHCiI7C8/hj0JOu07wz52GsDeIijkpcu1jPgoNNnRl4jaNv+1jnqtDNdojRFcj/xuH+J8CVGJfM835EmuV2Wkx/i5SebBG1auPzU+vir5vB0I8ZPan8d4uMyD6QaAHtfYyijU8cASLJW9RH5IBDTNlbuuj+aVA1GpLbR04SmsUOKTWbq4syTyLQWY6iCrJyOrB6pyTGmY0hXbacOTyxKkCVcYRchzeg9ip5lWDfAIPFoFpYdttZRNEBUGWkbc7EGrGOs2FNNTUry/EdoD4fan9ZTrFCwmvnT9tAVV+xZQJne23OgizMkyMdcBspkg+nSTdk8aSmnmGXQsjghmV/BMKKR91hUzlx7uNx+CtYA92vbCRwQ32JalaTBm3qIKZShZbhhVpf3gnRsdLlEd1NWECWjB/wXbUWSZqC9vJ9pIpMaijkicdibMZp9/g0T7mn4N5ZXxr/OrFKQYRnt36vuxFDNgksINI4fjQ=="}}

Response code

Other

{"trxInfo":{"deviceID":"A3B52F8
564AB42073F8CBC94568D3F3A7706E5274C650DDC76AC1C34642E3F54","enrolID":"216613","otpLength":"6","otpExpiry":"180","otpMaxAttempt":"10","supportedOtpMethod":"1"},"msgInfo":{"versionNo":"1.0.0","msgType":"SENDING_OTP","msgID":"A00010344200414051817000011","timeStamp":"20200414051817","walletID":"00000001"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1543312301","signature":"RIGZ2yyJY19SYlMq8hr8DW9dcnhHNuw6f0g0KdPVYYhZjw9q7U21v82THaPGGIrT9WpM/V0uilKzWnv1HrujUGXaEQqCO7Oban6Q3jonUbDH5EPO8W+f1yg7Uom/zmcCIMDoCepjVV7Wg8u5lhym0dZX6jtFlo9ZlptGor6qtgLkhTm0JvYYG6vLZcvhztwhJEx0ynH1kRkTQ3WbkS9bcBygnlYVPXFdJkZTp1DAiuQlkhv7XnbconTnkl0VzJAhYBrPcttCoIRDjlMZmS9/zgqAjtnvsWIXy0+HFA4hksmBy7pIQJkAxZQa5Z5F4rs/q1JIJFd9mkSDojP8seIV9Q=="}}

Interface description

The cardholder enters the OTP in the mobile application, and the mobile application will send it in the TOKEN_PROVISIONING request, along with the accepted TNCID. The UPI sends the OTP data for validation. If the validation is successful, the UPI will return the Token information to the application gateway.

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	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 "A0001034420171230235959000014"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_PROVISIONING" "TOKEN_PROVISIONING"
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
Enrollment ID	enrolID	N	16	M:Mandatory	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. "0000000000000009"
TNC ID	tncID	AN	1-20	M:Mandatory	The unique identifier of Terms and Conditions (TNC) "TNC01"
OTP Value	otpValue	ANS	1-9	C:Conditional	The OTP Value requested after SENDING OTP Message

Certificate and Signature

certificateSignature

object

M:Mandatory

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 "A0001034420171230235959000014"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "CARDFACE_DOWNLOADING" "CARDFACE_DOWNLOADING"
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	M:Mandatory	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. "0000000000000009"
Token	token	N	16-19	C:Conditional	Token PAN "6200008888888888888"
Cardface ID	cardfaceID	AN	1-20	C:Conditional	The identifier of the card image. It can be used in the CARDFACE_DOWNLOADING message.
Masked PAN	maskedPAN	ANS	16-19	C:Conditional	It is used to be displayed on the mobile application as the PAN, if necessary. "621111*********8888"
Masked Token	maskedToken	ANS	16-19	C:Conditional	It is used to be displayed on the mobile application, as the device PAN, if necessary. "620000*********8888"
Payment Account Reference	par	AN	29	C:Conditional	The Payment Account Reference number
Token State	tokenState	ANS	1-15	C:Conditional	Present if the Response Code is "00". Valid values: "INITIALIZED".
Token Expiry	tokenExpiry	N	12	C:Conditional	Format : YYYYMMDDhhmmss.

Message Response

msgResponse

object

M:Mandatory

Certificate and Signature

certificateSignature

object

M:Mandatory

Sample code

Request code

Other

{"msgInfo":{"versionNo":"1.0.0","msgID":"20200415144750004944","timeStamp":"20200415144750","msgType":"TOKEN_PROVISIONING","walletID":"39990004"},"trxInfo":{"deviceID":"28e5846283dc4b768814d485ff5a401d","enrolID":"216807","tncID":"27520702"},"certificateSignature":{"appSignCertID":"1509455488","umpsEncCertID":"1508413608","signature":"vGzM4Upf2Cgsrw8t2cJzkConwNIrZzzjjyhWSSJkG/DN+kMndQGfJZ12WKyq/jo7i/zHJagRcmKxY4iQGgPH3YFKTq6M4qQTtRAxTVG0Qdx4qgePuphM03QuPL25XPeLVBoZfJ1f8h+9P+TZWS/ukFg2bd44TrrPjZebeyxcpGmnJgj2CFiObLt7zv9y5hv24nwummCGNwvL/2hPmG5hmXt5cdWLmJ+Zxujgon6OrcHTuseajVk4wmKCrHUhqKLs/h4YREXr4gAmtcwdDOFvN592Cr+3Dq0+FoPcRemrTa9JdnSMiL6MFzPQSCvDNbTtffrD5CTrZKrTaQ5tA6NN8g=="}}

Response code

Other

{"trxInfo":{"deviceID":"28e5846283dc4b768814d485ff5a401d","enrolID":"216807","token":"6263600779297254","cardfaceID":"76","maskedPAN":"624466******8979","maskedToken":"626360******7254","par":"UP00BGUFX0B612TI6CBH1O37DPNIY","tokenState":"INITIALIZED","tokenExpiry":"251013000000","tokenRefID":"256701"},"msgInfo":{"versionNo":"1.0.0","msgType":"TOKEN_PROVISIONING","msgID":"20200415144750004944","timeStamp":"20200415144750","walletID":"39990004"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"H9exUqZgrfrkG0nt+hN6erdZ7EZ2vBkjJxOzKH++eDhF6BOTHedJE/oCguN4dq5pw5y/exuNJLubcIyXNXP5UcF+zdDsIIOvt03dzdxmgz9zxAVe3HQOZ1+mSE8OflpuzV5ylT+6USG6HCvvElJX/E66eeLqye64v07sOipL4XnyXtUQUnsxybReAUHefn8sM56oTw+twl/jTz+gvW6BqZFZLVnXnwlSCtR5wxW3rSkrYCsH8hFZDH0VmB8E+NiFsSJl1FdTLbUlN17IhOwnkA3cZ6myjsTFSfbSaZ0/wgHRlgw/Mv3Rua/gNqwwGbbHrkL0M9FrGbEWbnYty5TzAQ=="}}

Interface description

After loading Token information and completing the mobile application offline configuration, such as consumer device cardholder verification method, transaction amount limit, etc., the mobile application will send the TOKEN_STATE_UPDATE request to activate the Token for use in the payment. The UPI returns the result and the latest Token state in the TOKEN_STATE_UPDATE response message, and the enrollment process is completed.

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	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 "A0001034420171230235959000015"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_STATE_UPDATE" "TOKEN_STATE_UPDATE"
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
Enrollment ID	enrolID	N	16	C:Conditional	Present if it is an enrollment processing. 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.
Token	token	N	16	M:Mandatory	Token PAN
Token Action	tokenAction	ANS	1-15	M:Mandatory	Valid values: "ACTIVATE"; "SUSPEND"; "RESUME"; "DELETE".

Certificate and Signature

certificateSignature

object

M:Mandatory

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 "A0001034420171230235959000016"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_REQUEST" "TOKEN_REQUEST"
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	Present if it exists in the request. 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.
Token	token	N	16	M:Mandatory	Token PAN
Token State	tokenState	ANS	1-15	M:Mandatory	Valid values: "ACTIVE"; "SUSPENDED"; "DELETED".

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

Sample code

Request code

Other

{"certificateSignature":{},"msgInfo":{"msgID":"A3999000220171016093640556184","msgType":"TOKEN_PROVISIONING","timeStamp":"20171016093640","versionNo":"1.0.0","walletID":"39990002"},"trxInfo":{"deviceID":"4A728036-3DB0-4723-9CC6-D781CF5EBC1A","enrolID":"57043","otpValue":"085670","tncID":"99900702"}}

Interface description

"The mobile application can request to download the card face to display it to the cardholder. The UPI returns the card face data and the recommended PAN location in the CARDFACE_DOWNLOADING response."

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	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 "A0001034420171230235959000014"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "CARDFACE_DOWNLOADING"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

Transaction Information

trxInfo

object

M:Mandatory

Certificate and Signature

certificateSignature

object

M:Mandatory

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 "A0001034420171230235959000014"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "CARDFACE_DOWNLOADING"
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.
Card Face ID	cardfaceID	AN	1-20	M:Mandatory	The identifier of the card image to be downloaded "123"
Card Face Type	cardfaceType	N	1	C:Conditional	Valid Values:"0" :horizontal; "1": vertical.
PAN Position X	panPosX	N	3	C:Conditional	Position Y of PAN in Card Layout, value from “0” to “999”
PAN Position Y	panPosY	N	3	C:Conditional	Position Y of PAN in Card Layout, value from “0” to “999”
PAN Font Size	panFontSize	N	3	C:Conditional	PAN Font Size in Card Layout, value from 0 to 100
Text Color	color	AN	12	C:Conditional	Color of the Text Layout above in RRGGBB hexadecimal format
Card Face Data	cardfaceData	AN	1-2048000	C:Conditional	Data of image in Base64 format

Message Response

msgResponse

object

M:Mandatory

Certificate and Signature

certificateSignature

object

M:Mandatory

Interface description

After the mobile application has completed the account enrollment through its own network, it shall send a TOKEN_REQEUST request for the following payment.

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	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 "A0001034420171230235959000016"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_REQUEST" "TOKEN_REQUEST"
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. 　

Primary Account Number

pan

AN

1-2048

M:Mandatory

Encrypted with the public key of the Encryption Certificate Encrypted value of "6211110000000000000"

Use case Indicator

useCaseIndicator

array

1-100

M:Mandatory

List of the use cases in which the Token is allowed: Valid values are: "QRC".

Expiry Date

expiryDate

AN

M:Mandatory

The Expiry Date of the PAN. Format : MM/YY ; "12/22". Format: MM/YY

Cardholder Verification Method

cvm

array

1-255

M:Mandatory

List of the cardholder verification (CV) methods that the mobile application has performed. Valid CVs are : "expiryDate"; "cvn2"; "name"; "idType"; "idNo", "mobileNo"; "otp" . Note1:The "idType" and "idNo" shall be present together. Note 2: If no CV method is required, the object shall be "cvm": [ ] .

Risk Information

riskInfo

object

O:Optional

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. “5”
Device Type	deviceType	ANS	1-20	O:Optional	Valid Values: “MOBILE” Reserved Values: “WATCH” “PAD” “PC” “MOBILE”
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] Components: Country code (1-3 digits) + “-” + subscriber number If the country code is not present, UMPS will consider it as a Chinese mobile number. “86-13900000000”
GPS	gps	ANS	1-64	O:Optional	Components: +(-) latitude/+(-) longitude; Example: "+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. Format : YYMMDD. Example: "161230".
Card Number Capture Method	captureMethod	ANS	1-64	O:Optional	Valid Values: "MANUAL"; "NFC"; "CAMERA"; "UNKNOWN".
IP Address	ipAddress	ANS	1-64	O:Optional
Device Type	deviceType	ANS	1-20	O:Optional	Valid Values: “MOBILE”. Reserved Values: “WATCH”; “PAD”; “PC”.

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	1-128	C:Conditional	Present if encrypted information exists in the request message. 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 "A0001034420171230235959000016"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_REQUEST" "TOKEN_REQUEST"
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.
Token	token	N	16-19	C:Conditional	Present if the Response Code is "00".
Masked PAN	maskedPAN	ANS	16-19	C:Conditional	It is used to be displayed on the mobile application as the PAN, if necessary.
Masked Token	maskedToken	ANS	16-19	C:Conditional	Present if the Response Code is "00".
Payment Account Reference	par	AN	29	C:Conditional	The Payment Account Reference number
Token State	tokenState	ANS	1-15	C:Conditional	Present if the Response Code is "00". Valid values: "ACTIVE".
Token Expiry	tokenExpiry	N	12	C:Conditional	Format: YYMMDDhhmmss

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.

Certificate and Signature

certificateSignature

object

M:Mandatory

Sample code

Request code

Other

{"trxInfo":{"expiryDate":"08/21","useCaseIndicator":["QRC"],"cvm":["expiryDate","cvn2","mobileNo"],"pan":"aqBtsUh7AlvHMfeok2GZuuyWHlN2IWWRli/OHA/OdGtY6uZgyDvFKa1UgtU3O4HPWMY+8Jq3OiIf2aIbfsobcjGjShgBhd8c7006KiXlCVuzAR2erSmYtGCu7Kux2Af6jMrIGSB47bCKxhTBQsAw6tbUe5ER6+6sFECUB9QObIF/7GF1Pv1xoKE5qa4F6zjVIVpdHkny3w6zznUQT2WHcUrgYmsQaLOGmjMYmtXzoMZnReHTfORVJgXsiw1TmnFZX4xX9id1TXGF2XPRpy1d6hoY4IE7ku7cXM7QQfjJ6Jf6bB5HrxWvzpqXzoy8DxcFeyKx4sQ5OvbVgl6I6BEo3Q==","deviceID":"EB736206-AC5E-42C7-BCFA-79D4319C5294"},"certificateSignature":{"appSignCertID":"10050016685734906787","signature":"JXMo2DZcNFjtwjf7x9kWZFvORlpK1ocPvRml4VIZPi79DeKjeF1hxZE8jxjxJipymeyf9G0U/Zf2YgQ6uYslcc4ObIxHMWe5OJGccrJNhIfffcZIMRBPEtFNPoiQNibiUq0inRPFa5ISyDZ+E7eg61UnJgCN6ImWHrIRawj0Uqnx6Ufmw4A8O39tTVeoi4MVFZzArMc8mQni/AIF61D4EyjE49RTICP4SPOulMxmn06TNTF/6PTtgnVR8aiX0CK/OEA/x3bMXztVjmx+kghsKF3JP1gt+64R1eTg+w+R9BIJI73666rwxaJfHIEpv1S3vrRfRvy6x+QxaSj8hEiKNg==","umpsEncCertID":"1543312300"},"msgInfo":{"timeStamp":"20200415174302","walletID":"39990080","msgType":"TOKEN_REQUEST","versionNo":"1.0.0","msgID":"A3999008020200415174302471364"}}

Response code

Other

{"trxInfo":{"deviceID":"EB736206-AC5E-42C7-BCFA-79D4319C5294","token":"6291103371154201","maskedPAN":"624488******0675","maskedToken":"629110******4201","par":"UP001E6VLL6GNBH9ZAF2IHE0RG33J","tokenState":"ACTIVE","tokenExpiry":"211205000000"},"msgInfo":{"versionNo":"1.0.0","msgType":"TOKEN_REQUEST","msgID":"A3999008020200415174302471364","timeStamp":"20200415174302","walletID":"39990080"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1543312301","signature":"VHMZl40SP7X3+7AL4OA0/2BnXO7IuXCqHhO1SBPIfPgVy25YCS8URPY0W8TkLiQ0RixaLRjj5a6H35sFMZFrvNJZOkqTZjcvpWJ/chOcfC/X95KqyT3HRLhQKgYy3tjVASWLwbBNI3Pj0hRDvi+qqbg8qDVFP3QMiCIWqhetiEu8hB5OEw0CgSSiZk5ZOBNOZnwyEH1Pcue1LYn63PznnwGdUG4jE1E0jL4cZ4L3sa4cFLuVdJfgOln6OhU/rJ3dnckvZjGrYHJOYcrlDjsn0EZL49zY9tLrZpR8MKUFUuAKlGzZVQsus32j68uCctzKY1FGNP548ZFABiEvkRyZcQ=="}}

Interface description

When the UPI suspends, resumes, or deletes the card, the UPI will send the TOKEN_STATE_NOTIFICATION request to notify the mobile application.

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	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: “U”+Wallet ID+serial code "U0001034420171230235959000011"
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_STATE_NOTIFICATION" "TOKEN_STATE_NOTIFICATION"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

Transaction Information

trxInfo

object

M:Mandatory

Certificate and Signature

certificateSignature

object

M:Mandatory

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: “U”+Wallet ID+serial code "U0001034420171230235959000011"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TOKEN_STATE_NOTIFICATION" "TOKEN_STATE_NOTIFICATION"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

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

Interface description

After the consumer scans an EMV standard merchant-presented QR code, the merchant information shall be displayed on the application. After the consumer input required information, such as amount, loyalty number, etc. and confirm a purchase, the mobile application will initiate a QRC payment message to request an authorization from issuer. The payment message can be a purchase message, authorization message, etc.

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 wallet initiates on any day. The value in response must match the value in the request.Components: “A”+Wallet ID+ Serial Code"
Time Stamp	timeStamp	N	14	M:Mandatory	The value in response must match the value in the request. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "MPQRC_PAYMENT_EMV"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet

Transaction Information

trxInfo

object

M:Mandatory

Device ID

deviceID

ANS

1-64

M:Mandatory

The distinctive value associated to a device. This is required if PAN instead of Token is sent to identify the Token in UMPS.

Token

token

N

16-19

C:Conditional

Token PAN "6200008888888888888"

Primary Account Number

pan

AN

1-2048

C:Conditional

Encrypted with the public key of the Encryption Certificate. Please refer to Encrypt sample code in Documentation

Transaction ID

txnID

AN

17-49

M:Mandatory

"It is used to match a transaction to sequent messages within a transaction set. The transaction identifier will be the same in all related messages: MPQRC Payment, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the wallet initiates on any day.Components: “A”+Wallet ID+ Serial Code"

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

It is either key entered by consumer or captured by consumer mobile application from the merchant-presented QRC data, ID "54". The value in this field includes tip or convenience fee, if applicable. For example, the value of transaction amount (ID "54") in the dynamitic QRC data is "100". The value of fixed convenience fee (ID "56") is "1.10". Then the value of "trxAmt" shall be "101.10".The transaction amount in the response message shall be the approved amount.

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".

Merchant presented QR Code Payload

mpqrcPayload

S

1-512

M:Mandatory

It contains the raw payload data in the merchant-presented QR code.

Back URL

backURL

ANS

1-50

O:Optional

The UMPS system will send messages, such as TRX_STATUS_NOTIFICATION, back to this URL if it present. Otherwise, it will be sent back to the configured URL of the wallet.

Coupon Information

couponInfo

ANS

1-30

O:Optional

The coupon information will be encoded in the QR Code payload if sent in the request

Risk Information

riskInfo

object

O:Optional

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. “5”
Device Type	deviceType	ANS	1-20	O:Optional	Valid Values: “MOBILE” Reserved Values: “WATCH” “PAD” “PC” “MOBILE”
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] Components: Country code (1-3 digits) + “-” + subscriber number If the country code is not present, UMPS will consider it as a Chinese mobile number. “86-13900000000”
GPS	gps	ANS	1-64	O:Optional	Components: +(-) latitude/+(-) longitude. Example: "+37.12/-121.23".
SIM Card	simCard	array	1-200	O:Optional	The mobile number of the SIM cards. The mobile may have more than one SIM card. The gener
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. Format: YYMMDD. Example: "161230".
Card Number Capture Method	captureMethod	ANS	1-64	O:Optional	Valid Values: "MANUAL"; "NFC"; "CAMERA"; "UNKNOWN".
IP Address	ipAddress	ANS	1-64	O:Optional	The public network IP address of the device.

Additional Data

additionalData

object

C:Conditional

Present if the template "62" exists in the Merchant Presented QRC.

Bill Number	billNo	ANS	1-25	C:Conditional	Present if the ID "01" under template "62" exists in the Merchant Presented QRC. The invoice number or bill number. It may be provided by the merchant or entered by the consumer.
Mobile Number	mobileNo	ANS	1-25	C:Conditional	Present if the ID "02" under template "62" exists in the Merchant Presented QRC. The Mobile Number to be used for multiple use cases, such as mobile top-up and bill payment. It may be provided by the merchant or entered by the consumer. The mobile number may be different from the consumer mobile number, which will be passed to the acquirer/merchant as additional information.
Store Label	storeLabel	ANS	1-25	C:Conditional	Present if the ID "03" under template "63" exists in the Merchant Presented QRC. A distinctive value associated to a store. It may be provided by the merchant or entered by the consumer.
Loyalty Number	loyaltyNumber	ANS	1-25	C:Conditional	Present if the ID "04" under template "63" exists in the Merchant Presented QRC. Typically, a loyalty card number. It may be provided by the merchant or entered by the consumer.
Reference Label	referenceLabel	ANS	1-25	C:Conditional	Present if the ID "05" under template "64" exists in the Merchant Presented QRC. Any value defined by the merchant or acquirer in order to identify the transaction. It may be provided by the merchant or entered by the consumer.
Customer Label	customerLabel	ANS	1-25	C:Conditional	Present if the ID "07" under template "64" exists in the Merchant Presented QRC. Any value identifying a specific consumer. It may be provided by the merchant or entered by the consumer.
Terminal Label	terminalLabel	ANS	1-25	C:Conditional	Present if the ID "07" under template "64" exists in the Merchant Presented QRC. A distinctive value associated to a terminal in the store. It may be provided by the merchant or entered by the consumer.
Purpose of Transaction	trxPurpose	S	1-25	C:Conditional	Present if the ID "08" under template "65" exists in the Merchant Presented QRC. Any value defining the purpose of the transaction. It may be provided by the merchant or entered by the consumer.
Email Address of the Consumer	consumerEmail	S	1-100	C:Conditional	Present if the ID "09" under template "62" contains value "E" in the Merchant Presented QRC. The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the acquirer/merchant as additional information.
Address of the consumer	consumerAddress	S	1-100	C:Conditional	Present if the ID "09" under template "62" contains value "A" in the Merchant Presented QRC. The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the acquirer/merchant as additional information.
Mobile number of the consumer	consumerMobileNo	ANS	1-25	C:Conditional	Present if the ID "09" under template "62" contains value "E" in the Merchant Presented QRC. The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the acquirer/merchant as additional information.

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	1-128	C:Conditional	Present if encrypted information exists in the request message. The serial number of the certificate. The application 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 wallet initiates on any day. The value in the response must match the value in the request.Components:“A”+Wallet ID+ Serial Code "A0001034420171230235959000031"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "MPQRC_PAYMENT_EMV" "MPQRC_PAYMENT_EMV"
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.

Token

token

N

16-19

C:Conditional

Example: "6200008888888888888"

Primary Account Number

pan

AN

1-2048

C:Conditional

Encrypted with the public key of the Encryption Certificate

Transaction ID

txnID

AN

17-49

M:Mandatory

In the merchant-presented QRC mode, it must be populated with the same value of the QRC_INFO_INQUIRY.

Merchant-presented QR Code Payload

mpqrcPayload

AN

1-512

M:Mandatory

It contains the raw payload data in the merchant-presented QR code.

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

It is either key-entered by consumer or captured by consumer mobile application from the merchant-presented QRC data, ID "54". The value in this field includes tip or convenience fee, if applicable.

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 mobile application can display the transaction currency in a readable way, such as "RMB".

Discount

discount

ANS

1-13

O:Optional

The amount of discount. Example: "20"

Original Amount

originalAmount

ANS

1-13

M:Mandatory

The original amount. Example: "101.10"

Merchant Name

merchantName

ANS

1-40

C:Conditional

Example: "UnionPay International"

QRC Voucher Number

qrcVoucherNo

ANS

1-20

C:Conditional

Example: "1234567890123456789"

Back URL

backURL

ANS

1-50

O:Optional

The UMPS system will send messages, such as TRX_STATUS_NOTIFICATION, back to this URL if it is present. Otherwise, it will be sent back to the configured URL of the wallet. Example: "https://www.unionpayintl.com"

Coupon Information

couponInf

ANS

1-30

O:Optional

If sent in the request, the coupon information will be encoded in the QR Code payload.

Retrieval Reference Number

retrievalReferenceNumber

AN

12

C:Conditional

Settlement Key

settlementKey

object

C:Conditional

Acquirer IIN	acquirerIIN	AN	8	C:Conditional	Example: "00010344"
Forwarding IIN	forwardingIIN	AN	8	C:Conditional	Example: "00010344"
System Trace Audit Number	systemTraceAuditNumber	N	6	C:Conditional	Example: "000001"
Transmission Date and Time	TransmissionDateTime	N	10	C:Conditional	Format: MMDDhhmmss

Risk Information

riskInfo

object

O:Optional

GPS	gps	ANS	1-64	O:Optional	Components: +(-) latitude/+(-) longitude
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. Format: YYMMDD
Card Number Capture Method	captureMethod	ANS	1-64	O:Optional	Valid Values: "MANUAL", "NFC", "CAMERA", "UNKNOWN"
IP Address	ipAddress	ANS	1-64	O:Optional	The public network IP address of the device
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number. If the country code is not present, UMPS will consider it as a Chinese mobile number.
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.

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.
	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.

Certificate and Signature

certificateSignature

object

M:Mandatory

Sample code

Request code

Other

{"msgInfo":{"versionNo":"1.0.0","msgID":"A3999999920200415173134978509","timeStamp":"20200415173134","msgType":"MPQRC_PAYMENT_EMV","walletID":"39999999"},"trxInfo":{"deviceID":"0ada14cd21593b12d56a594be6561c9c","token":"6292610306159930031","txnID":"A3999999920200415173134978509","trxAmt":"1","mpqrcPayload":"xxxxxxxxxxxx","additionalData":{"billNo":"00000000000000000000","referenceLabel":"00000000000000000000","terminalLabel":"00000002"}},"certificateSignature":{"appSignCertID":"1564028313749","signature":"kI0eLrBBE9jcn3e+dRxFrWERWRv1fmSCTeJCWRfyLhPJgxypIHDJlDPSjLUsUvRPo9V1modv0CAV9OLykxIFv6nrzzDUM++ZoiYqHqQOcb/swxxT/0NZVVsIOBugkqOzSv6IsefC+3IE9HkTog4GuHndW0HxuQcCyoesy8uEpdfmC6ugu29cww/eLMYEr3HqyyGM49216cSnstZ8iZOrtCkiYuwD+StC286/ZwzJY3E3WniQqEnmPHjN/ySAcMH/kdWto7+brFWtx98jybUy2T4Z7DGkzMPy12oAq4O9XGDEPM9436J99pUFmVnULcYgM4ETl+4dsFkRlUdeZbsLsA=="}}

Response code

Other

{"trxInfo":{"txnID":"A3999999920200415173134978509","trxAmt":"1.00","trxCurrency":"344","qrcVoucherNo":"20206106824158796101","retrievalReferenceNumber":"041533795482","settlementKey":{"acquirerIIN":"25000344","forwardingIIN":"00020344","systemTraceAuditNumber":"188619","TransmissionDateTime":"0415173134"}},"msgInfo":{"versionNo":"1.0.0","msgType":"MPQRC_PAYMENT_EMV","msgID":"A3999999920200415173134978509","timeStamp":"20200415173134","walletID":"39999999"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1543312301","signature":"bhLVRHxlH9mHXCb1R+CzM/sofn3btnVWLEpz6KaDt7Mw6M9zM+Py1qKYU/qHuQg6hN7TJy8TYNF7wbH0BHEYLKMJ2lTVgVNtJBRwjtMwYCpCX2EE07+5P5icxCmC4EfQroyKzJOIfoGWgNRhoXliH41M8Oyi6WROfUt1lxlGsC1GR69Zzwn5rSiKlel1+s0/wD9fybYtVWEMdkORDgAW3HH0cVVPVd0hsoKlLptXCdWKUzi+Ojmd3MviGid0Y3wY2Ok/TlBgtKIhAhBkLagjFGk+3xoVjCO8VzjA4B4nod75EuMcSkcS0d+C3rQUwqbbDt4tQdG11+cQ8TLJTXfcHA=="}}

Interface description

Gateway of traffic entrance ask a transaction result inquiry to UPI. UPI requests switch and respondes.

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	17-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+ Serial Code. Example: "A0001034420171230235959000032".
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. 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: "TRX_RESULT_INQUIRY" "TRX_RESULT_INQUIRY"
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.
Token	token	N	16-19	C:Conditional	"6200008888888888888"
Primary Account Number	pan	AN	1-2048	C:Conditional	Encrypted with the public key of the Encryption Certificate. Please refer to Encrypt sample code in Documentation
Transaction ID	txnID	AN	17-49	M:Mandatory	In the merchant-presented QRC mode, it must be populated with the same value of the merchant presented QRC payment. "A0001034420171230235959000090"

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	1-128	C:Conditional	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.

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 wallet initiates on any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code "A0001034420171230235959000032"
Time Stamp	timeStamp	N	14	M:Mandatory	Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "TRX_RESULT_INQUIRY" "TRX_RESULT_INQUIRY"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

Transaction Information

trxInfo

object

M:Mandatory

Transaction Amount

trxAmt

ANS

1-13

C:Conditional

Approved transaction amount. "101.10"

Transaction Currency

trxCurrency

N

3

C:Conditional

A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB". Example: "156".

Discount

discount

ANS

1-13

O:Optional

The amount of discount "20"

Original Amount

originalAmount

ANS

1-13

O:Optional

The original amount 　

Merchant Name

merchantName

ANS

1-40

C:Conditional

Present if the Response Code is "00"."UnionPay International"

QRC Voucher Number

qrcVoucherNo

ANS

1-20

C:Conditional

C Populated by UnionPay if it exists. 　 "1234567890123456789"

Retrieval Reference Number

retrievalReferenceNumber

AN

12

C:Conditional

C Populated by UnionPay if the payment is approved. 　　

Settlement Key

settlementKey

object

C:Conditional

Acquirer IIN	acquirerIIN	AN	8	C:Conditional	Populated by UnionPay if the payment is approved. Example: "00010344".
Forwarding IIN	forwardingIIN	AN	8	C:Conditional	Populated by UnionPay if the payment is approved. Example: "00010344".
System Trace Audit Number	systemTraceAuditNumber	N	6	C:Conditional	Populated by UnionPay if the payment is approved. Example: "000001".
Transmission Date and Time	TransmissionDateTime	N	10	C:Conditional	Format : MMDDhhmmss. Populated by UnionPay if the payment is approved. Example: "1230235959". Format: MMDDhhmmss

Payment Status

paymentStatus

ANS

1-20

M:Mandatory

Valid Values: "APPROVED": The QRC payment is approved. "CANCELLED": The QRC payment is cancelled. "REFUNDED": The QRC payment is refunded. "REJECTED": The QRC payment is rejected.

Rejection Reason

rejectionReason

S

1-100

C:Conditional

Present if the Payment Status is "REJECTED" The rejection reason of the additional processing. Please refer to the Response Code and Message for details.

Message Response

messageResponse

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

Sample code

Request code

Other

{"trxInfo":{"deviceID":"D7DA4AFF760A7841ECD2C5F3B73F4ADF4129640D294F84D1C3C604A4A50CCEA0","token":"6292600022841622","txnID":"A00010344200415052818000001"},"msgInfo":{"versionNo":"1.0.0","msgType":"TRX_RESULT_INQUIRY","msgID":"A00010344200415052822000003","timeStamp":"20200415052822","walletID":"00000001"},"certificateSignature":{"appSignCertID":"201806211822","signature":"Un05XfB01gbJ/qKtLkALj3g1Klx6LpknWMsgbGmCpFD1ySNJ4y4jzwSd3KVxvTS29KiMdQfwTSBJpgqbguzbdwYEz8nEw7tXxFJBJE7hTyj5B9oLJgOtWJJ3jUzt8dtxHHGcnDnn/Fptn6az2AKGzR0nkMFqte2RsGxQfG1YxIuEstVQ10GECEwNPx6dStFAv5Y5ks1LbWlyfmNyhHEwReABP2Z9/vc7H/495Qzf8i1erTNgU4ddt0LuJZHofZ3AkrV9OSJjcN8urnKSOchPCIajt8WdELspg0BukeTgdzrJ8BSd3Wl0oWeAKY2CkhWCMG+QUzK2pqGqIURFuEDS0Hlq0Db1z5LKTl0uIzVq9UkX31fL9Jl45N2HOMVqO6NI3B+AV26jUZ2iR6ImWw5okzWiJd1WJ3KW+9V9aBVGoPXilfInnKWHxE92YKvB3YXGp8B85MjlZDlxmTwSTDKJhQ5ef1NFPStfPprLP3lE5Uaj+9FUJ8N1FweUzp2WofHmdtbLhr7ZJoAEZJH5KM1gczRkvKSSEMpjQ5FF08fBto5b5RoWNG+nd+PA96tPzSJelUaSC8NtFqgn9YyiJsWXZnQA9JjhiiDxIy/w7IU0U6Q8nStK+LJIww5dZaWkBwcpt8hUApFaGbyR7c6nV8q4UoDRZKZ2vWnVUdkDieVjni60Qlm48zdU8koH3Ig9hCztMMT39fkYDSrbPFV3NOuI/dQ1C5Zxsq6RwZYYLVAbMYNjvhMiKRrBzMRvdfmYkMYqdzn8rLPRGIW2MiUPFqily8WNQWlw0aMnD9jxRYC90JfgQwzOOUQnHixEivxAlCEIGdHLBmcdYeqa4UByPW3QOQ=="}}

Response code

Other

{"trxInfo":{"trxAmt":"10.00","originalAmount":"10.00","trxCurrency":"458","merchantName":"TestStoreID","qrcVoucherNo":"20206106689310086749","retrievalReferenceNumber":"041517282198","settlementKey":{"acquirerIIN":"37060458","forwardingIIN":"00520446","systemTraceAuditNumber":"188617","TransmissionDateTime":"04106052821"},"paymentStatus":"APPROVED"},"msgInfo":{"versionNo":"1.0.0","msgType":"TRX_RESULT_INQUIRY","msgID":"A00010344200415052822000003","timeStamp":"20200415052822","walletID":"00000001"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1543312301","signature":"shVdA8QruREhw+0wVEjCvn153aUnEbBva8ZiAaFWimIBslUx76Cdx4SILRA/+ADV9zVNWjyAyew1egPnAAzu35bwNEZztvIM+23hmI4jMKTESyW/IhiQrgvXyVuvTU8Tin+MwUlNvDZO0uw+/CJbGWYkfBCF3oZid17IX/KDGwQ/hR/epeh2OzQ3RwwLhs5NkmexZ3HJzQocN4+17rG2it+kXY3lWbBav50UHyMmZR0Aqp0bqxoOVKQVd7tPR5LObvU+7gEkH0ufHZLpTDuTdN6PkPkJdTGpzhkuUs+lZYEgGo34mULbXuCW7r7CqHSsSeejz3cBXeoSAKLkz4t5fQ=="}}

Interface description

Gateway of the app ask a QRC information inquiry to UPI at merchant-presented mode, and UPI would responde with merchant information and other QR Code info details.

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 wallet initiates on any day. The value in response must match the value in the request.Components: “A”+Wallet ID+ Serial Code"
Time Stamp	timeStamp	N	14	M:Mandatory	Fprmat:YYYYMMDDhhmmss.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: "QRC_INFO_INQUIRY".
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.
Merchant presented QR Code Payload	mpqrcPayload	S	1-512	M:Mandatory	It contains the raw payload data in the merchant-presented QR code.
Transaction ID	txnID	AN	17-49	M:Mandatory	It is used to match a transaction to sequent messages within a transaction set. The transaction identifier will be the same in all related messages: MPQRC Payment, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the wallet initiates on any day.Components: “A”+Wallet ID+ Serial Code.example:"A0001034420171230235959000091".

Certificate and Signature

certificateSignature

object

M:Mandatory

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 wallet initiates on any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code.example:"A0001034420171230235959000033".
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss.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: "QRC_INFO_INQUIRY".
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.
Transaction ID	txnID	AN	17-49	M:Mandatory	It is used to match a transaction to sequent messages within a transaction set. The transaction identifier will be the same in all related messages: MPQRC Payment, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the wallet initiates on any day.Components: “A”+Wallet ID+ Serial Code.example:"A0001034420171230235959000091".
Transaction Amount	trxAmt	ANS	1-13	C:Conditional	The value in this field includes tip or convenience fee, if applicable."101.10"
Transaction Currency	trxCurrency	N	3	C:Conditional	A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB".
QRC Use Case	qrcUseCase	N	2	C:Conditional	Valid Values: "10": purchase transaction；"11": purchase transaction, debit card only. Example: purchase finance products. "12": purchase transaction in small businesses. "20": ATM withdrawal. Reserved."31": P2P QRC payment, debit card only. Reserved.
Merchant Name	merchantName	S	1-40	C:Conditional	Present if the Response Code is "00". 　 "UnionPay International"
Merchant Category Code	mcc	N	4	C:Conditional	Present if the Response Code is "00". 　 Convenience store is represented by "5411".
Merchant Country Code	merchantCountry	ANS	2	O:Optional	"CN"
Merchant City	merchantCity	ANS	1-15	O:Optional	"Shanghai"
Postal Code	postalCode	ANS	1-10	O:Optional	"200120"
Language Preference	languagePreference	AN	2	O:Optional	"zh"
Merchant Name Alternate Language	merchantNameAL	S	1-25	O:Optional	"银联国际"
Merchant City Alternate Language	merchantCityAL	S	1-15	O:Optional	"上海"
Terminal ID	terminalID	ANS	1-15	O:Optional

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

Sample code

Request code

Other

{"msgInfo":{"versionNo":"1.0.0","msgID":"A00000001202004231120582317","timeStamp":"20200423112058","msgType":"QRC_INFO_INQUIRY","walletID":"00000001"},"trxInfo":{"deviceID":"D3616AE813F97299DB450BA8BE60ABE9F164F71F1B0703E78764CD7601BAED87","mpqrcPayload":"https://qr.95516.com/01040000/0120084588379999987089","txnID":"A00000001202004231120583217"},"certificateSignature":{"appSignCertID":"201806211822","signature":"a297wGbnRs4Nmnz2lVX0vPuBTJYV3rv2RFjqwD3P7bOKZVL/kIA4LQKrtyVHblR8Q8SzwhFKhioD1Wav32h9rGe7703iDjerdo/dtD2U1ENknNt3NsO0/t1aHrFN/mhF+mrN0iFKvkC1YE3cdIcKkZGEya7yZH0NU6YS/IYdn3cQRw5FSxFt0Fi5Ll79tlJ6DU97B7coYUKzZaOewo9jf1lCtmXdMGo9l+FKoFlyAjRM4WccokawyZMrHR+NHDS+9kS8kLGEfAraC/PnyFXNE+0LPVnvNwu1oizGyM2Yo1Q1ncrsJ1adkRpfDp3jhJPxZO+VpWycy0gv5lDieDAk124qqiXJSxsJ8ypiwNKT5SB6gDqoiQqm8F63yD5azwhrMPSJtxZD/f6PVm6XICt8m+g7rI8nyZzK3XELFBbn27zdiLUdVN5tMqTBb6HAuC66JMOZ+JYePM0wIJAuWahkKZRKKclUV3i6uYnF+cqqZYupVw/gRh+PICDpViyL6OVKvGvaDy/o8kSOZcioW9bWubMyJDGhUJcHTdYaLNLCVQTnz/JroK5ov96HMzoJiRLDx9w0RGJrEeX19ZFPcUAjZczy1VH6WfiMnTj5ngHBSmz/eJeeWKabXC6fjPnIB/nv956UW/brFjoeaCPiIaF/CjRRCP4GloARg33HSSVE7vyAqUh5LHdbAeFbRRfbo1UK2GgskJ1zjxi0MaWwMz8i6LrtFU+1CSdDLFQv7e6waxVyQpS4fE2QtMUy6ig=="}}

Response code

Other

{"trxInfo":{"deviceID":"D3616AE813F97299DB450BA8BE60ABE9F164F71F1B0703E78764CD7601BAED87","txnID":"A00000001202004231120583217","trxCurrency":"156","mcc":"4458","merchantName":"广东行测试商户","qrcUseCase":"10"},"msgInfo":{"versionNo":"1.0.0","msgType":"QRC_INFO_INQUIRY","msgID":"A00000001202004231120582317","timeStamp":"20200423112058","walletID":"00000001"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1543312301","signature":"UxrOKA0zilx7/v85ACDoGoRw7xhGoA87KPsjsTT1KU567qAdkClzlkYU8f3foiNsRnavesKhBsw802L2xq8xlnOE/4TOJwnpqamsTfYzZs3fCSmoLxyJvKka8WxcvcGN7EkTj4ZrWEkT/TrPh923azKzUFAfR+0ON1Qos0bq6r9s3xOaH1Tdn37R3Vq3z+RetLp7khOA6rZ3+2kKOM/4ofqtEocXQSeO0ctG/Phd55m5ykS5L4E2FC2bqxgjCuupaH5cbrKwQGtBj9kNzeWq5L1j3tLpglLkpEIz3tH7Wpdd4iH3K6/9fJoX6ulUES5yv959xyQpQ5kZ1akLuGgVFw=="}}

Interface description

After the consumer an URL standard merchant-presented QR code, the mobile application will initiate a merchant information inquiry message to request the merchant name, merchant ID etc. Once the consumer confirms the payment, the mobile application will initiate a payment message to request an authorization from issuer. The payment message can be a purchase message, authorization message, etc.

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	17-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code "A0001034420171230235959000033"
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "MPQRC_PAYMENT_URL".
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.

Token

token

N

16-19

C:Conditional

　 "6200008888888888888"

Primary Account Number

pan

AN

1-2048

C:Conditional

Encrypted with the public key of the Encryption Certificate. Please refer to Encrypt sample code in Documentation

Transaction ID

txnID

AN

17-49

M:Mandatory

In the merchant-presented QRC mode, it must be populated with the same value of the QRC_INFO_INQUIRY. "A0001034420171230235959000091"

Merchant presented QR Code Payload

mpqrcPayload

S

1-512

M:Mandatory

It contains the raw payload data in the merchant-presented QR code. 　

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

It is either key-entered by consumer or captured by consumer mobile application from the merchant-presented QRC data, ID "54". The value in this field includes tip or convenience fee, if applicable. For example, the value of transaction amount (ID "54") in the dynamitic QRC data is "100". The value of fixed convenience fee (ID "56") is"1.10". Then the value of "trxAmt” shall be "101.10".

Back URL

backURL

ANS

1-50

O:Optional

The UMPS system will send messages, such as TRX_STATUS_NOTIFICATION, back to this URL if it is present. Otherwise, it will be sent back to the configured URL of the wallet.

Coupon Information

couponInfo

ANS

1-30

O:Optional

If sent in the request, the coupon information will be encoded in the QR Code payload.

Risk Information

riskInfo

object

O:Optional

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. “5”
Device Type	deviceType	ANS	1-20	O:Optional	Valid Values: “MOBILE” Reserved Values: “WATCH” “PAD” “PC” “MOBILE”
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] Components: Country code (1-3 digits) + “-” + subscriber number If the country code is not present, UMPS will consider it as a Chinese mobile number. “86-13900000000”
GPS	gps	ANS	1-64	O:Optional	Components: +(-) latitude/+(-) longitude.example:"+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	Format:YYMMDD.
Card Number Capture Method	captureMethod	ANS	1-64	O:Optional	Valid Values:"MANUAL"; "NFC"; "CAMERA";"UNKNOWN".
IP Address	ipAddress	ANS	1-64	O:Optional	The public network IP address of the device

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	1-128	C:Conditional	The serial number of the certificate. The application 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 wallet initiates on any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code.example:"A0001034420171230235959000033".
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "MPQRC_PAYMENT_URL" "MPQRC_PAYMENT_URL"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

Transaction Information

trxInfo

object

M:Mandatory

Transaction ID

txnID

AN

17-49

M:Mandatory

In the merchant-presented QRC mode, it must be populated with the same value of the QRC_INFO_INQUIRY. "A0001034420171230235959000091"

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

It is either key-entered by consumer or captured by consumer mobile application from the merchant-presented QRC data, ID "54". The value in this field includes tip or convenience fee, if applicable. For example, the value of transaction amount (ID "54") in the dynamitic QRC data is "100". The value of fixed convenience fee (ID "56") is "1.10". Then the value of "trxAmt” shall be "101.10". "101.10"

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 mobile application can display the transaction currency in a readable way, such as "RMB".

Discount

discount

ANS

1-13

O:Optional

The amount of discount "20"

Original Amount

originalAmount

ANS

1-13

O:Optional

The original amount 　"101.10"

Merchant Name

merchantName

ANS

1-40

C:Conditional

Present if the Response Code is "00". 　 "UnionPay International"

QRC Voucher Number

qrcVoucherNo

ANS

1-20

C:Conditional

Populated by UnionPay if the payment is approved."1234567890123456789"

Retrieval Reference Number

retrievalReferenceNumber

AN

12

C:Conditional

Populated by UnionPay if the payment is approved.

Settlement Key

settlementKey

object

C:Conditional

Acquirer IIN	acquirerIIN	AN	8	C:Conditional	Populated by UnionPay if the payment is approved. 　 "00010344"
Forwarding IIN	forwardingIIN	AN	8	C:Conditional	Populated by UnionPay if the payment is approved. 　 "00010344"
System Trace Audit Number	systemTraceAuditNumber	N	6	C:Conditional	Populated by UnionPay if the payment is approved. 　 "000001"
Transmission Date and Time	TransmissionDateTime	N	10	C:Conditional	Format:MMDDhhmmss.example:"1230235959". Format: MMDDhhmmss

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.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 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

Sample code

Request code

Other

{"msgInfo":{"versionNo":"1.0.0","msgID":"A399900440000017139","timeStamp":"20200415174409","msgType":"MPQRC_PAYMENT_URL","walletID":"39990044"},"trxInfo":{"deviceID":"707FA47A-5090-47AB-8417-6A676FD09A80","pan":"Rd7b9BSRRz7xDKFuSUOs5tZsE/uZQqbande83ILPAUjPrrweV2d5Y3q8UaYl3ccKi9ABy5h7aK8P93mOvCF2PSQs53bawmyTCXVse82jWmJqwUH2Lbmlw/s+OgiyUHcFFEfuSJnogVhn5yl4jy68ShFFzwRCaFLOHHHFmhXDVzNIestG+SsM/t4ZSrdyd7DpqktgZ8AfUIdvTHCKzrnkA+9twtuaxOEPtxTOMaxArMwSMhgT+vvi1MeLoOgUxQzmCxcz4MxtlR4Zr0jXOOqdELRyfwyYm2CO2J+oAa5jiOKRgVOWgc3/GypGjhVL/6lEWj+UzNs6ltJW4biOIFlMTA==","txnID":"A399900440000017138","mpqrcPayload":"https://qr.95516.com/01040000/0120084588379999987089","trxAmt":"60.11","backURL":"http://184.6.11.187:19092/boc/bcss/umpsqrgw","riskInfo":{"appUserID":"E3B31FE857AF200B1D9C1DEBCF398539","reservedMobileNo":"15818108768"}},"certificateSignature":{"appSignCertID":"1508406698","umpsEncCertID":"1508413608","signature":"g7ljbU/cS9o9s+lWYUCZ9q12BoTQlRJqMkLRP4wAUnbp3+n8VIEJMbi0gQY+uzOeIromJzZg1wea/ruYKamEIAR/WUHGmAox6yGqfYfjDvarASr37LjSnJ69Srr/s+ObmLL3qmCTYRB19nfAqNVzySUbJYqjjgK7tgwt3se0ZNs="}}

Response code

Other

{"trxInfo":{"txnID":"A399900440000017138","trxAmt":"59.23","originalAmount":"6011","trxCurrency":"156","merchantName":"广东行测试商         ","qrcVoucherNo":"672635617823271","retrievalReferenceNumber":"RC9999713335","settlementKey":{"acquirerIIN":"01040000","forwardingIIN":"00049992","systemTraceAuditNumber":"781951","TransmissionDateTime":"0415173938"},"discountDetails":[{"discountAmt":"0.88","discountNote":"深信随机立减-gd"}]Info":{"versionNo":"1.0.0","msgType":"MPQRC_PAYMENT_URL","msgID":"A399900440000017139","timeStamp":"20200415174409","walletID":"39990044"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"m8+m244HlFrYd+3ogxTxFAL4ndKGU49s5/s5Kqm2ZcKG2kSvGFJYWqcYYIYvwVeHTwv6Gzt5YnNrrR8GL3gGgUtzxAI1PRC2gSEM/Q//VfG0HMrbOwCAGjVDsYkhm1xBgdugHcmGT4FEUBlLDjzOR1zcgHsiHgW/Hv2pk3llM7qMA+JxIZVmeDQL6+YOFUhJV+TYkwJsDTZwApp6AHe6jUVZmMGy5p5KlIhx/+6h5RfsC63ULhKZHpA3QzOfq5ANjM+HDCGkKP/zxVq/tMYOeqMgKlNr1LgKvm+27fTVQRK9LuR8yK5LUlJV/WFPLNAkM4WfdSs7cZ8IJG1svunYXg=="}}

Interface description

When the consumer select a QR option, the mobile application can send a message and request a consumer-presented QR code payload.

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	17-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code. example:"A0001034420171230235959000021".
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. 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: "CPQRC_GENERATION".
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. This is required if PAN instead of Token is sent to identify the Token in UMPS.

Token

token

N

16-19

C:Conditional

　 "6200008888888888888"

Primary Account Number

pan

AN

1-2048

C:Conditional

Encrypted with the public key of the Encryption Certificate Encrypted value of "6211110000000000000"

Transaction Limit

trxLimit

ANS

1-13

O:Optional

“300.00”

CVM Limit

cvmLimit

ANS

1-13

O:Optional

“150.00”

Limit Currency

LimitCurrency

N

3

C:Conditional

Present if either “trxLimit” or “cvmLimit” exists “156”

Consumer presented QRC Number

cpqrcNo

N

2

M:Mandatory

The mobile application is allowed to request more than one QR codes. This field indicates the number of the requested QR codes.

Back URL

backURL

ANS

1-50

O:Optional

The UMPS system will send messages, such as Additional Processing, TRX_STATUS_NOTIFICATION, back to this URL if it is present. Otherwise, it will be sent back to the configured URL of the wallet.

Coupon Information

couponInfo

ANS

1-30

O:Optional

If sent in the request, the coupon information will be encoded in the QR Code payload.

Risk Information

riskInfo

object

O:Optional

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. “5”
Device Type	deviceType	ANS	1-20	O:Optional	Valid Values: “MOBILE” Reserved Values: “WATCH” “PAD” “PC” “MOBILE”
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] Components: Country code (1-3 digits) + “-” + subscriber number If the country code is not present, UMPS will consider it as a Chinese mobile number. “86-13900000000”
GPS	gps	ANS	1-64	O:Optional	Components: +(-) latitude/+(-) longitude. example: "+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	Format:YYMMDD.
Card Number Capture Method	captureMethod	ANS	1-64	O:Optional	Valid Values: "MANUAL";"NFC"; "CAMERA";"UNKNOWN".
IP Address	ipAddress	ANS	1-64	O:Optional	The public network IP address of the device

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	1-128	C:Conditional	The serial number of the certificate. The application 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 wallet initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+ Serial Code "A0001034420171230235959000021"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "CPQRC_GENERATION" "CPQRC_GENERATION"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

Transaction Information

trxInfo

object

M:Mandatory

Consumer presented QRC Number	cpqrcNo	N	2	C:Conditional	The mobile application is allowed to request more than one QR code. This field indicates the number of the requested QR codes. "2"
EMV Consumer presented QR Code Payload	emvCpqrcPayload	array	1-2000	C:Conditional	It contains the raw payload data. The array shall be as follows:"emvcpqrcPayload": [emv payload1, emv payload2, … ,emv payloadN].
Barcode Consumer-presented QR Code Payload	barcodeCpqrcPayload	array	1-2000	C:Conditional	It contains the raw payload data. The array shall be as follows:"barcodeCpqrcPayload": [barcode payload1, barcode payload2, … barcode payloadN].example:["6212345678901234567","6212345678907654321"].

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

Sample code

Request code

Other

{"trxInfo":{"cpqrcNo":"1","cvmLimit":"0","limitCurrency":"344","deviceID":"A574B94A-DFCD-494E-95A2-90018654DD7D","token":"6263600562176657"},"certificateSignature":{"appSignCertID":"273473560882061111584571817585031905202309390377","signature":"DF4wXPPcfVfhVwXGbuXt+XhWKcdel16KGoSXEfuwJFJodT2m+xMpE1JI/y6sIDdP1nuFDXP0roE3akV9OnQAtGRWHAGwYrYhjSpp9CkQros6h0mgDpZ/w2fsPaBfkgx5HN+UoQjdNjZlXq/ucR/mo8e27Bo/qJs5EXGWjYp52kXme+ahjKUiJPPG/7iw4+2wfE/ivWPY5h4Lft07nzQDG7qg4/1I68zzTLN3n7naojloffC7zH5PEV0hj7bB9fXVOs2zK2vvDB7xsWp31Cogl+z6l5DZa4PEkac9nijoOfG2D9TvwR5MI4LhVO4gyGfrdBdSZ/DJ4+s3Uc4XfzxgEg=="},"msgInfo":{"timeStamp":"20200415172941","walletID":"39990072","msgType":"CPQRC_GENERATION","versionNo":"1.0.0","msgID":"A39990072202004151729419261578028171262"}}

Response code

Other

{"trxInfo":{"cpqrcNo":"1","emvCpqrcPayload":["hQVDUFYwMWFWTwigAAADMwEBAlcRYmNgBWIXZlfSMFIBAAABiAFfNAEAYzOfJghWiwQ+33OkCp8nAYCfEBEHAAEDoAAAAQgzOTk5MDA3Mp82AnAhggIAAJ83BDyV33Y="],"barcodeCpqrcPayload":["6236082777107964938"]},"msgInfo":{"versionNo":"1.0.0","msgType":"CPQRC_GENERATION","msgID":"A39990072202004151729419261578028171262","timeStamp":"20200415172941","walletID":"39990072"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"VahUm0oOzEQOXGNAXK3Oux4KLnL4zkiES+Iyu+Lb29rWRGHEouMqxMQt/KgLDAU1d02fTmmC1NkTQMurH1pOxANsWP3hVLu/a2nhkiTdyDB5PefV6vj/jQRgNw5ub77b23vwaHeNMcAopiAJGPw+q4iqVJ6LuXypM3B4HqMdW7i0cCsq5uFsL0Oni785XkqW/CIR880JiZdsp2AyekVt0R//bYvACxrUvcOxF1ez8YiDGuMjY5jMtheUfDKTOMaqUdV/cfBm56LvKyvw6Uzl7rjCJKG1macJwt8GyukObUx89QNXrMaOYCYtMzPD6nt6yZnGPu+JMbkLbNmSZh6RZw=="}}

Interface description

UPI verifies whether the transaction amount is higher than CVM limit. If yes, UPI will send an ADDITIONAL_PROCESSING request to app gateway, and app gateway respondes and notifies the app for cardholder to verify the cvm.

Request Method

HTTP GET

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	17-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request.Components: “U”+Wallet ID+ Serial Code. example:"U0001034420171230235959000021".
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. 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: "ADDITIONAL_PROCESSING".
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	C:Conditional	The distinctive value associated to a device. This is required if PAN instead of Token is sent to identify the Token in the UMPS.
Token	token	N	16-19	C:Conditional	Token PAN "6200008888888888888"
Primary Account Number	pan	AN	1-2048	C:Conditional	Encrypted with the public key of the Encryption Certificate Encrypted value of "6211110000000000000"
EMV Consumer presented QR Code Payload	emvCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (EMV format) used in the payment transaction. Only one payload is allowed to be present.
Barcode Consumer presented QR Code Payload	barcodeCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (barcode) used in the payment transaction. Only one payload is allowed to be present. " 6212345678901234567".
Transaction Amount	trxAmt	ANS	1-13	M:Mandatory	The transaction amount. The mobile application can display the transaction amount to the cardholder. example:"101.10".
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 mobile application can display the transaction currency in a readable way, such as "RMB". example:"156".
Merchant Name	merchantName	S	1-40	M:Mandatory	The merchant name. The value of this field can be displayed on the mobile application to the cardholder.

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.
Application Encryption Certificate ID	appEncCertID	AN	1-128	C:Conditional	The serial number of the certificate. The UMPS 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 wallet initiates on any day. The value in the response must match the value in the request.Components: “U”+Wallet ID+ Serial Code "U0001034420171230235959000021"
Time Stamp	timeStamp	N	14	M:Mandatory	Format:YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "ADDITIONAL_PROCESSING" "ADDITIONAL_PROCESSING"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

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

Sample code

Request code

Other

{"trxInfo":{"deviceID":"45b73e86-8bc2-47bd-b8b1-647236ab7ba4","token":"6263600541570632","emvCpqrcPayload":["hQVDUFYwMWFWTwigAAADMwEBAlcRYmNgBUFXBjLSMIIBAAABiAFfNAEAYzOfJghWivtwEShnap8nAYCfEBEHAAEDoAAAAQgzOTk5MDA3Mp82AhkiggIAAJ83BDVyS4I="],"trxAmt":"10.00","trxCurrency":"702","merchantName":"CHN29000CHINA UNIONPAY SIMULATOR "},"msgInfo":{"versionNo":"1.0.0","msgType":"ADDITIONAL_PROCESSING","msgID":"U39990072000000000000638349","timeStamp":"20200415164451","walletID":"39990072"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"00000000"}}

Response code

Other

{"certificateSignature":{"appSignCertID":"273473560882061111584571817585031905202309390377","signature":"00000000"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"msgInfo":{"timeStamp":"20200415164451","walletID":"39990072","msgType":"ADDITIONAL_PROCESSING","versionNo":"1.0.0","msgID":"U39990072000000000000638349"}}

Interface description

APP sends an ADDITIONAL_PROCESSING_RESULT request to UPI. If the result of the additional processing is positive, then UPI requests authorization for issuer, otherwise UPI will reject the transaction and notifies the acquirer.

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	17-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+ Serial Code "A0001034420171230235959000022"
Time Stamp	timeStamp	N	14	M:Mandatory	Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "ADDITIONAL_PROCESSING_RESULT".
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	C:Conditional	The distinctive value associated to a device. This is required if PAN instead of Token is sent to identify the Token in the UMPS.
Token	token	N	16-19	C:Conditional	"6200008888888888888"
Primary Account Number	pan	AN	1-2048	C:Conditional	Encrypted with the public key of the Encryption Certificate Encrypted value of "6211110000000000000"
EMV Consumer presented QR Code Payload	emvCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (EMV format) used in the payment transaction. Only one payload is allowed to be present.
Barcode Consumer presented QR Code Payload	barcodeCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (barcode) used in the payment transaction. Only one payload is allowed to be present. example:6212345678901234567.
Payment Status	paymentStatus	ANS	1-20	M:Mandatory	Valid Values:"CONTINUING": The additional processing is successful, and the payment shall continue;"REJECTED": The additional processing fails, and the payment shall be rejected. example:"CONTINUING".
Rejection Reason	rejectionReason	S	1-100	C:Conditional	The rejection reason of the payment. Please refer to the Response Code and Message for details.

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	1-128	C:Conditional	The serial number of the certificate. The application 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 wallet initiates on any day. The value in the response must match the value in the request. Components: “A”+Wallet ID+ Serial Code "A0001034420171230235959000022"
Time Stamp	timeStamp	N	14	M:Mandatory	Format：YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	Valid Value: "ADDITIONAL_PROCESSING_RESULT" "ADDITIONAL_PROCESSING_RESULT"
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet "00010344"

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

Sample code

Request code

Other

{"trxInfo":{"emvCpqrcPayload":["hQVDUFYwMWFWTwigAAADMwEBAlcRYmNgBUFXBjLSMIIBAAABiAFfNAEAYzOfJghWivtwEShnap8nAYCfEBEHAAEDoAAAAQgzOTk5MDA3Mp82AhkiggIAAJ83BDVyS4I="],"deviceID":"45b73e86-8bc2-47bd-b8b1-647236ab7ba4","paymentStatus":"CONTINUING","token":"6263600541570632"},"certificateSignature":{"appSignCertID":"273473560882061111584571817585031905202309390377","signature":"wQg/hTFS9Kt16whaAU+uh0hlTbYiYO9lo4chCUEVGiErgQzZEnzgUK4aHLZtz0iwecmlHG7hQuOSmRBCGYeUCbBTSTiBQn0FAlxYYJ/iScDlebiq5+pD63inuYNZrM7KiZAr3wUK4baKYDdN6sGb33ezoIlTdB1tu7b7H86FkqHgTLLSg9FT7uvDE4HT3/zlvDld472qghQENAXdCsq0ADbV7kaKBcTDy3StoqEVxnLyLOhDBRlUMNF/s0f/V7Geyb/Aa6rZX/rn8Pm4UP5zbGYLphnY5u4no3DwPLUlidvVcJyRnwKvJsWpFkGZlWTI95icVyZSxZsoVpxX01bcuQ=="},"msgInfo":{"timeStamp":"20200415164451","walletID":"39990072","msgType":"ADDITIONAL_PROCESSING_RESULT","versionNo":"1.0.0","msgID":"A39990072202004151644519258887873923785"}}

Response code

Other

{"trxInfo":{"deviceID":"45b73e86-8bc2-47bd-b8b1-647236ab7ba4"},"msgInfo":{"versionNo":"1.0.0","msgType":"ADDITIONAL_PROCESSING_RESULT","msgID":"A39990072202004151644519258887873923785","timeStamp":"20200415164451","walletID":"39990072"},"msgResponse":{"responseCode":"00","responseMsg":"Approved"},"certificateSignature":{"umpsSignCertID":"1508413609","signature":"CvINW1zxLX2SY0GBz1B+fFl12lJLT6NiDhvDHXl1r+nlqL3mGfNp5F7ahpSavzWvOYdKFiQkxcjbG4lyVPqOp8sWnAAyKDHdyI5lWsttqm/uQBtYLpBqTQNRyElRn90m5atRTVQK07yyd/N1ZzPfRDgSbjVD1FkEFCyZl/WxmPNT6EZ/S5ZWYLmoZXe1P7ZhYeAOahrfA1ifePGgwjIjNkagaNFKFLF5fvoIRG7aw3deYQlm/9BioyagH+uZoCGdV8q/o3f8SJ3Xk86NR5rUqhZGfHk7lNCunPXQRge209cTIQKhoruDm7ZgoxsupEm/f26OIqp/soFKcDo1mxV6aQ=="}}

Interface description

UPI transfers the notification to app gateway, while app gateway sends a response message to UPI.

Request Method

HTTP GET

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	14-49	M:Mandatory	It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates on any day. The value in the response must match the value in the request.Components: “U”+Wallet ID+ Serial Code. example:"U0001034420171230235959000023".
Time Stamp	timeStamp	N	14	M:Mandatory	format:YYYYMMDDhhmmss. 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: "TRX_STATUS_NOTIFICATION".
Wallet ID	walletID	AN	8	M:Mandatory	The distinctive value associated to a wallet. example:"00010344".

Transaction Information

trxInfo

object

M:Mandatory

Device ID	deviceID	ANS	1-64	C:Conditional	The distinctive value associated to a device. This is required if PAN instead of Token is sent to identify the Token in the UMPS.
Token	token	N	16-19	C:Conditional	Token PAN "6200008888888888888"
Primary Account Number	pan	AN		C:Conditional	Encrypted with the public key of the Encryption Certificate Encrypted value of "6211110000000000000"
Transaction ID	txnID	AN	17-49	C:Conditional	"A0001034420171230235959000090"
EMV Consumer presented QR Code Payload	emvCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (EMV format) used in the payment transaction. Only one payload is allowed to be present.
Barcode Consumer presented QR Code Payload	barcodeCpqrcPayload	array	1-2000	C:Conditional	The consumer-presented QR code payload (barcode) used in the payment transaction. Only one payload is allowed to be present. example:"6212345678901234567".
Transaction Amount	trxAmt	ANS	1-13	M:Mandatory	The transaction amount. The mobile application can display the transaction amount to the cardholder. example:"101.10".

Card Product

Online Payment

Mobile QuickPass

QR Code

Cross-Border B2B Service

Token Program

SaaS Card Issuing Service Platform

Block Chain

Platforms

Global Service

Digital Solutions

Industry Solutions

Deferred Online ODA Mode

Real-Time Mode

Frictionless Parking

Transit QR Code Mode