UnionPay International Developer

Open API >Online Payments >ExpressPay

ExpressPay

Online Payments Merchant Acquirer Internet Payment

ExpressPay is designed to provide a easy and widely-supported payment method.

API Introduction

Key Features

ExpressPay (UPOP Mode, hereinafter referred to as ExpressPay) provides a fast and convenient UnionPay online payment solution to acquirers and merchants. It allows cardholder to stay on merchant/acquirer page to complete a payment on different terminals, such as PC, laptop, tablet and other mobile devices. ExpressPay will process E-commerce Non-Authentication mode transactions for acquirers. ExpressPay can accept UnionPay credit cards, signature debit cards, signature prepaid cards, and PIN debit/PIN prepaid cards issued outside Mainland China, Hong Kong and Macau. This mode allows acquirers or merchants to utilize UPOP system’s interface via Internet.

Who Use it?

Acquirers, Merchants and Developers

Where to Use it?

This API is available globally except for mainland China

Flow Chart

ExpressPay流程图.png

1. Cardholder chooses product on a merchant website;

2. The merchant initiates a request message to the acquirer system;

3. The acquirer transfers the transaction to UnionPay Omnichannel Platform (UPOP);

4.UPOP transfers the transaction to UnionPay core processing system;

5. UnionPay core processing system converts FX rate and transfers the transaction to the issuer;

6. Issuer authorizes transaction and the response message goes back to the merchant website over the same route.

* For ExpressPay, acquirers can integrate to UPOP system via internet or integrate to UPI core processing system via leased line.

API Reference

encryption public key certificate update inquiry transaction
Transaction state inquiry transaction
Purchase transaction
Purchase cancellation transaction
Refund transaction
Pre-authorization transaction
Pre-authorization Cancellation transaction
Pre-authorization Completion transaction
Pre-authorization Completion Cancellation transaction

Interface description

UnionPay encryption public key certificate update inquiry transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK is provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	95: Encryption public key certificate update inquiry
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: Default
Certificate type	certType	N	2	M:Mandatory	01: encryption public key certificate
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access1: Acquirer access
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Fill the MCC. Applied if access type is acquirer access.
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer accessDo not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer accessDo not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Transaction time of queried transaction. Format: YYYYMMDDhhmmss
Reserved field	reserved	ANS	1-2048	O:Optional	Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned	5.1.0: Fixed value
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Encoding method	encoding	ANS	1-20	R:Returned	Fill in with the character encoding used for message
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	Value: same as the queried transaction
Transaction sub-type	txnSubType	N	2	M:Mandatory	Value: same as the queried transaction
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Transaction time of queried transaction Format: YYYYMMDDhhmmss
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Return the requestor reserved field for the queried transaction
Reserved field	reserved	ANS	1-2048	O:Optional
Response code	respCode	AN	2	M:Mandatory	For details please refer to Part IV A.1 response code
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed Response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method
Public key certificate for encryption	encryptPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for encryption when certificate is updated
Certificate type	certType	N	2	R:Returned

Interface description

Transaction state inquiry transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	ANS	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK is provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	00: Transaction state inquiry
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	ANS	6	M:Mandatory	000000: Default
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Transaction time of queried transaction. Format: YYYYMMDDhhmmss
Reserved field	reserved	ANS	1-2048	O:Optional	Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned	5.1.0: Fixed value
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Encoding method	encoding	ANS	1-20	R:Returned	Fill in with the character encoding used for message
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	Value: same as the queried transaction
Transaction sub-type	txnSubType	N	2	M:Mandatory	Value: same as the queried transaction
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned	0: Merchant direct access.1: Acquirer access
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned	Applied if access type is acquirer access
Merchant ID	merId	AN	15	R:Returned	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Transaction time of queried transaction Format: YYYYMMDDhhmmss
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Return the requestor reserved field for the queried transaction
Transaction query number	queryId	AN	21	M:Mandatory	Query number of queried transaction
System Trace Audit Number	traceNo	N	6	M:Mandatory	Returned by system.System assigns each transaction a System Trace Audit Number.
Transmission date and time	traceTime	N		M:Mandatory	Returned by system Format: MMDDhhmmss
Settlement date	settleDate	N		C:Conditional	The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12,DD: 1-31 Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	ANS	1-12	C:Conditional	Financial transaction returned by system.Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	Financial transaction returned by system.This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12,DD: 1-31 Format: MMDD
Transaction currency	currencyCode	AN	3	M:Mandatory	Value: Same as the queried transaction
Transaction amount	txnAmt	ANS	1-12	M:Mandatory	Value: Same as the queried transaction
Original transaction response code	origRespCode	AN	2	C:Conditional	Returned if transaction inquiry is successful
Original transaction Response information	origRespMsg	ANS	1-256	C:Conditional	Returned if transaction inquiry is successful
Response code	respCode	AN	2	M:Mandatory	For details please refer to Part IV A.1 response code
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed Response information
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03:Quasi-credit account.04: Credit/Debit account.05: Prepaid account
Issuer institution identify mode	IssuerIdentifyMode	N	1	C:Conditional	Returned for purchase and pre-authorization transaction:1: Non-authentication mode
Payment card number	payCardNo	ANS	1-19	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Payment card name	payCardIssueNa	ANS	1-64	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Purchase transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	01: Purchase
Transaction sub-type	txnSubType	N	2	M:Mandatory	01: Purchase, to differentiate the front-end purchase or back-end purchase through transaction request URL
Product type	bizType	N	6	M:Mandatory	000000: System default value, applicable for expresspay, and QRC Payment
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Fill the MCC. Applied if access type is acquirer access.
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of purchase transaction, generated by merchant.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Time merchant sent transaction Format: YYYYMMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	Submit complete card number.Must be encrypted through a public key encryption and perform Base64 encoding before submission.
Transaction amount	txnAmt	N	1-12	M:Mandatory	When the transaction currency is RMB, the last two digits in the right of this field should contain Jiao and Fen in RMB.When the transaction currency is non-RMB and has no decimal digit, this field reflects the actual transaction amount. If the currency is non-RMB and has two decimal digits, the way to fill the field is the same as that of RMB; while if it has three decimal digits, the last three digits are decimal digits. Please refer to Part IV Annex A.2 for currency decimal digits.
Transaction currency	currencyCode	AN	3	M:Mandatory	If transaction currency is Vietnamese dong and Indonesian rupiah, then it must submit reserved sub-field currency accuracy field.Note: UnionPay use 3 digits currency code
Cardholder verification information	customerInfo	ANS	1-1024	C:Conditional	ExpressPay:Credit card:CVN2: optional.Expiration date: Mandatory.For usage details, please refer to section 0 the usage description of customerInfo field.
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	O:Optional	Format is as follows: {variable name 1 = value1 & variable name 2 = value2 & variable name 3 = value3}, please refer to subfield description for details.
Encryption certificate ID	encryptCertId	N	1-128	C:Conditional	The serial number of public key certificate for encryption.Applied if sensitive information (CVN2, expiration date) or PAN, mobile number is encrypted.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquirer ID	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Transaction currency	currencyCode	AN	3	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	C:Conditional	Purchase transaction query number, used in follow-up inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Transaction currency	currencyCode	AN	3	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Transaction query number	queryId	AN	21	M:Mandatory	Purchase transaction query number, used in follow-up inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Settlement Date	settleDate	N		C:Conditional	The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	N	1-12	C:Conditional	Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:.00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account
Payment card number	payCardNo	ANS	1-19	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Payment card name	payCardIssueNa	ANS	1-64	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Purchase cancellation transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	31: Purchase cancellation
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant’s type	merCatCode	N	4	C:Conditional	Applied if access type is acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of purchase cancellation, generated by merchant. It should be unique at merchant side and should not be the same as original transaction’s merchant order number.Should not contain ‘-’ and ‘_’
Original transaction query number	origQryId	AN	21	M:Mandatory	Original purchase transaction's query ID
Order time	txnTime	N		M:Mandatory	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	M:Mandatory	Matches original transaction
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	C:Conditional	Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original purchase query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
UnionPay transaction query number	queryId	AN	21	M:Mandatory	Purchase cancellation transaction query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original purchase query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction currency	currencyCode	AN	3	M:Mandatory
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Purchase cancellation transaction query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Settlement Date	settleDate	N		C:Conditional	The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	N	1-12	C:Conditional	Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Refund transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	04: Purchase refund
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Applied if access type is acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of refund, generated by merchant. It should be unique at merchant side and should not be the same as original transaction’s merchant order number.Should not contain ‘-’ and ‘_’
Original transaction query number	origQryId	AN	21	M:Mandatory	Original purchase/pre-authorization completion transaction's query ID
Order time	txnTime	N		M:Mandatory	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	M:Mandatory
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	C:Conditional	Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned	04: Purchase refund
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original purchase/pre-authorization completion transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Refund transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original purchase/pre-authorization completion transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction currency	currencyCode	AN	3	M:Mandatory
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Refund transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory	Fill in detailed response information
Response information	respMsg	ANS	1-256	M:Mandatory	The settlement related fields only returned by system for successful financial transaction.
Settlement Date	settleDate	N		C:Conditional	The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	N	1-12	C:Conditional	Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	This field is only used when the transaction currency is different from the settlement currency. The value range is:MM: 1-12.DD: 1-31 Format: MMDD
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Pre-authorization transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	02: Pre-authorization
Transaction sub-type	txnSubType	N	2	M:Mandatory	01: Pre-authorization
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Applied if access type is Acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of pre-authorization, generated by merchant.Should not contain ‘-’ and ‘_’
Order time	txnTime	N		M:Mandatory	Format: YYYYMMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	Submit complete card number.Must be encrypted Encryption public key and perform Base64 encoding before submission.
Transaction amount	txnAmt	N	1-12	M:Mandatory	When the transaction currency is RMB, the last two digits in the right of this field should contain Jiao and Fen in RMB.When the transaction currency is non-RMB and has no decimal digit, this field reflects the actual transaction amount. If the currency is non-RMB and has two decimal digits, the way to fill the field is the same as that of RMB; while if it has three decimal digits, the last three digits are decimal digits. Please refer to Part IV Annex A.2 for currency decimal digits.
Transaction currency	currencyCode	AN	3	M:Mandatory	If transaction currency is Vietnamese dong and Indonesian rupiah, reserved sub-field currency accuracy field must be submitted.Note: UnionPay uses numeric currency code.
Cardholder verification information	customerInfo	ANS	1-1024	C:Conditional	ExpressPay:Credit card:CVN2: optional.Expiration date: Mandatory.For usage details, please refer to section 0 the usage description of customerInfo field.
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	C:Conditional	Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.
Encryption certificate ID	encryptCertId	N	1-128	C:Conditional	The serial number of public key certificate for encryption.Applied if sensitive information (CVN2, expiration date) or PAN, mobile number is encrypted.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	3	R:Returned
Transaction sub-type	txnSubType	N	3	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Transaction currency	currencyCode	AN	3	M:Mandatory
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization transaction query number, used in follow-up inquiries.
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Transaction currency	currencyCode	AN	3	M:Mandatory
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization transaction query number, used in follow-up inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account.
Payment card number	payCardNo	ANS	1-19	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Payment card name	payCardIssueNa	ANS	1-64	C:Conditional	Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Pre-authorization Cancellation transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	32: Pre-authorization cancellation
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Applied if access type is acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.8 Chinese characters or 8 characters.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of pre-authorization cancellation, generated by merchant. It should be unique at merchant side and should not be the same as original transaction’s merchant order number.Should not contain ‘-’ and ‘_’
Original transaction query number	origQryId	AN	21	M:Mandatory	Original pre-authorization transaction's query ID
Order time	txnTime	N		M:Mandatory	Time merchant sent transaction Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	M:Mandatory	Matches original pre-authorization transaction
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	C:Conditional	Format is as follows: {variable name 1 = value1 & variable name 2 = value2 & variable name 3 = value3}, Please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization cancellation transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction currency	currencyCode	AN	3	M:Mandatory
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization cancellation transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Pre-authorization Completion transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK is provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01:RSA
Transaction type	txnType	N	2	M:Mandatory	03: Pre-authorization completion
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Access type	accessType	N	1	M:Mandatory	0：Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Applied if access type is acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.8 Chinese characters or 8 characters.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of pre-authorization completion, generated by merchant..Should not contain ‘-’ and ‘_’
Original transaction query number	origQryId	AN	21	M:Mandatory	Original pre-authorization transaction's query ID
Order time	txnTime	N		M:Mandatory	Time merchant sent transaction Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	M:Mandatory
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	1-2048	C:Conditional	Format is as follows: {sub-field key 1 = value1 & sub-field key 2 = value2& sub-field key 3 = value3 }, Please refer to subfield description for details

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization completion transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction currency	currencyCode	AN	3	M:Mandatory
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization completion transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Settlement Date	settleDate	N		C:Conditional	The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12.DD: 1-31. Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	N	1-12	C:Conditional	Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Interface description

Pre-authorization Completion Cancellation transaction

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	M:Mandatory	5.1.0: Fixed value
Encoding method	encoding	ANS	1-20	M:Mandatory	UTF-8: Default value
Certificate ID	certId	N	1-128	M:Mandatory	The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature	signature	ANS	1-1024	M:Mandatory	Fill in message hash signature
Signature method	signMethod	N	2	M:Mandatory	01: RSA
Transaction type	txnType	N	2	M:Mandatory	33: Pre-authorization completion cancellation
Transaction sub-type	txnSubType	N	2	M:Mandatory	00: Default
Product type	bizType	N	6	M:Mandatory	000000: ExpressPay
Access type	accessType	N	1	M:Mandatory	0: Merchant direct access.1: Acquirer access
Channel type	channelType	N	2	M:Mandatory	07: Internet.08: Mobile
Back-end URL	backUrl	ANS	1-256	M:Mandatory	Used for sending back-end notification to merchant. If merchant or acquirer need to be notified via leased lines, should add prefix “ZX\|” before the notification address.
Acquiring Institution Identification Number	acqInsCode	AN	8-11	C:Conditional	Applied if access type is acquirer access
Merchant ID	merId	AN	15	M:Mandatory	The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type	merCatCode	N	4	C:Conditional	Applied if access type is acquirer access
Merchant name	merName	ANS	1-40	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant abbreviation	merAbbr	ANS	1-8	C:Conditional	Applied if access type is acquirer access.Do not support invisible characters such as newline
Merchant order number	orderId	AN	8-40	M:Mandatory	Order number of pre-authorization completion cancellation, generated by merchant. It should be unique at merchant side and should not be the same as original transaction’s merchant order number.Should not contain ‘-’ and ‘_’
Original transaction query number	origQryId	AN	21	M:Mandatory	Original pre-authorization completion transaction's query ID
Order time	txnTime	N		M:Mandatory	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	M:Mandatory
Requestor reserved field	reqReserved	ANS	1-1024	O:Optional	Merchant self-defined reserved field, it will be returned without change in transaction response.
Reserved field	reserved	ANS	2048	C:Conditional	Format is as follows: {sub-field key 1 = value1 & sub-field key 2 = value2 & sub-field key 3 = value3}, Please refer to subfield description for details.

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization/pre-authorization completion transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization completion cancellation transaction's query number for use in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Asynchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Version number	version	NS	5	R:Returned
Encoding method	encoding	ANS	1-20	R:Returned
Signature	signature	ANS	1-1024	M:Mandatory
Signature method	signMethod	N	2	M:Mandatory
Transaction type	txnType	N	2	R:Returned
Transaction sub-type	txnSubType	N	2	R:Returned
Product type	bizType	N	6	R:Returned
Access type	accessType	N	1	R:Returned
Acquiring Institution Identification Number	acqInsCode	AN	8-11	R:Returned
Merchant ID	merId	AN	15	R:Returned
Merchant order number	orderId	AN	8-40	R:Returned
Original transaction query number	origQryId	AN	21	R:Returned	Original pre-authorization/pre-authorization completion transaction's query ID
Order time	txnTime	N		R:Returned	Format: YYYYMMDDhhmmss
Transaction currency	currencyCode	AN	3	M:Mandatory
Transaction amount	txnAmt	N	1-12	R:Returned
Requestor reserved field	reqReserved	ANS	1-1024	R:Returned
Reserved field	reserved	ANS	1-2048	O:Optional
Transaction query number	queryId	AN	21	M:Mandatory	Pre-authorization completion cancellation transaction's query number used in inquiries
Response code	respCode	AN	2	M:Mandatory
Response information	respMsg	ANS	1-256	M:Mandatory	Fill in detailed response information
Settlement Date	settleDate	N		C:Conditional	The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Settlement currency	settleCurrencyCode	AN	3	C:Conditional	Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount	settleAmt	N	1-12	C:Conditional	Settlement amount＝transaction amount ×settlement conversion rate
Conversion Rate	exchangeRate	N	8	C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date	exchangeDate	N		C:Conditional	This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
System Trace Audit Number	traceNo	N	6	M:Mandatory
Transmission date and time	traceTime	N		M:Mandatory	Format: MMDDhhmmss
Primary Account Number (PAN)	accNo	AN	1-1024	C:Conditional	The account number must be decrypted through a private key.
Account attribute	payCardType	N	2	C:Conditional	Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account.
Public key certificate for Signature	signPubKeyCert	AN	2048	C:Conditional	Return UnionPay public key certificate for signature when RSA is used as signature method

Steps to Launch

Please provide the following information to developer@unionpayintl.com , in order for a UnionPay International representative to assist you with your business launch.

1. Company Name

2. Contact Person's Name

3. Phone

4. Business Scope

5. Regions and Countries

6. UnionPay Product

7. Monthly Volumn of Online Business Transaction (USD)

FAQ and Documentation

Documents:

ExpressPay 5.1 SDK for Acquirer .rar

Update time: 2021-04-09 17:46:28
ExpressPay 5.1 SDK for Merchant .rar

Update time: 2021-04-09 17:47:03

Response Code Reference

Response code	Description
00	Success
01	Transaction failed. For details please inquire overseas service hotline
02	System is not started or temporarily down, please try again later
03	Transaction communication time out, please initiate inquiry transaction
05	Transaction has been accepted, please inquire about transaction result shortly
06	System is busy, please retry it later.
10	Message format error
11	Verify signature error
12	Repeat transaction
13	Message transaction key element missing
30	Transaction failed, please try using other UnionPay card for payment or contact overseas service hotline
31	Merchant state incorrect. The payment is not completed within the order timeout.
32	No such transaction right
33	Transaction amount exceeds limit
34	Could not find this transaction
35	Original transaction does not exist or state is incorrect
36	Does not match original transaction information
37	Max number of inquiries exceeded or too frequent operations
38	UnionPay risk constraint
39	Transaction is not within the acceptance time range
42	Balance deduction successful but transaction exceeded payment time limit
43	Business not allowed, please contact overseas service hotline for help.
44	Wrong number entered or business not opened, please contact overseas service hotline for help.
45	The original transaction has been refunded or cancelled successfully.
60	Transaction failure, for details, please inquire with your issuer
61	Card number entered is invalid, please double check and enter
62	Transaction failed, issuer does not support this merchant, please change to another bank card
63	Card state is incorrect
64	Card balance is insufficient
65	Error with PIN, expiration date, or CVN2 entered, transaction failure
66	Cardholder identity information or mobile number entered are incorrect, verification failure
67	Limit on number of PIN entry attempts exceeded
68	Your bank card currently does not support this business, please inquire with your bank or overseas service hotline for help
69	Time limit on entry exceeded, transaction failure
70	Transaction has been redirected, waiting for cardholder input
71	Dynamic password or SMS verification code validation failure
72	You have not signed up for UnionPay card-not-present payment service at the bank counter or on your personal online bank, please go to a bank counter or access your online banking to activate it or contact overseas service hotline for help.
73	Payment card has exceeded expiration date
76	Requires encryption verification for activation
77	Bank card has not been activated for authenticated payment
78	Issuer transaction rights limited, for details please contact your issuer
79	The bank card is valid, but issuer does not support SMS verification
80	Transaction failed and the token has expired
81	Monthly accumulated transaction counter (amount) exceeded
82	PIN needs to be verified
84	PIN is required but not submitted
85	Transaction failed, the marketing rules are not met
86	QRC status error
88	QRC not found
89	No Token found, invalid TR status or invalid Token status
98	File does not exist
99	General error

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

Prompt

Kindly Reminder

Prompt