One-Stop Cross-Border Shopping — Shop the World
UnionPay Content & Service Platform (UCSP) for Channel Partner
UnionPay Content & Service Platform (UCSP) for Service Provider
UnionPay Transportation Solutions
The API is based on ApplePay SDK for acquirer (Indirect Merchant). It contains back-end SDK for UPOP5.0/5.1 interface. Merhcant APP shall collect payment information and send it to the acquirer/gateway. Acquirer/gateway can initiate the transaction via the back-end interface to UPOP5.0/5.1. The back-end interface can be developed via the back-end SDK.
The pricing strategy of In-App transactions currently follows the UPI E-Commerce pricing strategy.
UPI In-App Apple Pay (In-direct Mode) Payment provides a convenient and secure channel for the cardholder to finish the Apple Pay payment within the merchant APP without re-direction. The payment can be initiated by the acquirers/gateways via internet access.
Escpecially, In-App Apple Pay supports the calling of QuickPass to finish payment.
UnionPay Apple Pay SDK will be used to help merchant provide the payment service. And the SDK will be resopnsible for securely collecting payment information and completing transaction.
1) In-App Payment shall support purchase, inquiry and back-end notification receival. Other transactions will be optional.
2) The In-App Apple Pay (In-direct Mode) Payment transactions can be processed via the back-end interface to UPOP5.0/5.1. Please note the transaction differences while using the testing URL and the production URL.
3) Certificate of testing environment is contained in the back-end SDK package.
1. Cardholder chooses Apple Pay in the merchant APP;
2. The merchant collects Apple Pay payment data and initiates a request message to the acquirer system;
3. The acquirer transfers the request 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. The issuer authorizes transaction and the response message goes back to the merchant over the same route.
Field name | Identifier | Type | Length | Request | Default value | 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 | 00: Transaction state inquiry | ||
Transaction sub-type | txnSubType | N | 2 | M:Mandatory | 00: Default | ||
Product type | bizType | N | 6 | M:Mandatory | 000000: Default | ||
Access type | accessType | N | 1 | M:Mandatory | 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-1028 | 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. |
Filed name | Identifier | Type | Length | Request | Default value | 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 | 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 | ||
Reserved field | reserved | ANS | 1-2048 | C:Conditional | Please refer to reserved field definition for details | ||
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 | N | 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 | N | 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 | Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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:0: Authentication mode.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. | ||
Card-Present transaction information field | cardTransData | ANS | 1-2048 | C:Conditional | Applied for card-present transactions. Please refer to 4.5.5 for details.Return sub-field IC card data ICCardData only in response message. | ||
Public key certificate for Signature | signPubKeyCert | AN | 2048 | C:Conditional | Return UnionPay public key certificate for signature when RSA is used as signature method |
Field name | Identifier | Type | Length | Request | Default value | Note | |
---|---|---|---|---|---|---|---|
Version number | version | NS | 5 | M:Mandatory | 5.1.0 | 5.1.0: Fixed value | |
Encoding method | encoding | ANS | 1-20 | M:Mandatory | UTF-8 | ||
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 | 01: Purchase | |
Transaction sub-type | txnSubType | N | 2 | M:Mandatory | 01 | 01: Default | |
Product type | bizType | N | 6 | M:Mandatory | 000802 | 000802: AM remote payment | |
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Acquirer code | acqInsCode | AN | 8-11 | M:Mandatory | To be sent when the access type is Acquirer Access | ||
Channel type | channelType | N | 2 | M:Mandatory | 08 | ||
Back-end notification address | backUrl | ANS | 1-256 | M:Mandatory | Used in the back-end notification of merchant’s result; if sent,merchant’s back-end transaction result notification will be sent. If the notification is sent by leased lines, a prefix should be added in front of the notification address: Initials of the leased lines plus a vertical line, ZX| | ||
Merchant code | merId | AN | 15 | M:Mandatory | The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID. | ||
Merchant category | merCatCode | N | 4 | M:Mandatory | Fill in MCC code; needs to be sent when the access type is Acquirer Access | ||
Merchant name | merName | ANS | 1-40 | M:Mandatory | Applied if access type is acquirer access. Do not support invisible characters such as newline | ||
Merchant abbreviation | merAbbr | ANS | 1-8 | M:Mandatory | To be sent when the access type is Acquirer Access | ||
Merchant order number | orderId | AN | 8-40 | M:Mandatory | Order number of purchase transaction, generated by merchant. Should not contain ‘-’ and ‘_’ | ||
Sending time of orders | txnTime | N | M:Mandatory | Transaction sending time by merchants,format:YYYYMMDDhhmmss Format: YYYYMMDDhhmmss | |||
Account No | accNo | AN | 1-1024 | M:Mandatory | DPAN (Apple Pay token) | ||
Transaction amount | txnAmt | N | 1-12 | M:Mandatory | |||
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 | ||
Bankcard verification info and ID info | customerInfo | ANS | 1-1024 | C:Conditional | (1) Mainly fill in the cardholder's name (paymentData->data->cardholderName in PassKitApi) and payment password (paymentData->data-> encryptedPINData in PassKitApi) (2) Do not send if there is no returning in PassKitApi | ||
Requestor reserved field | reqReserved | ANS | 1-1024 | O:Optional | Merchant self-defined reserved field, it will be returned without change in transaction response. | ||
Card transaction information field | cardTransData | ANS | 1-2048 | M:Mandatory | Card transaction information field : Fill in ICCardData (paymentData->data-> paymentData-> emvData in PassKitApi) and carrierTp=6 and carrierAppTp=2 |
Filed name | Identifier | Type | Length | Request | Default value | 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 code | acqInsCode | AN | 8-11 | C:Conditional | |||
Merchant code | merId | AN | 15 | R:Returned | |||
Merchant order number | orderId | AN | 8-40 | R:Returned | |||
Sending time of orders | txnTime | N | R:Returned | Format:YYYYMMDDhhmmss 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 message | respMsg | ANS | 1-256 | M:Mandatory | Fill in detailed response information | ||
Signature Public Key Certificate | signPubKeyCert | AN | 2048 | C:Conditional | "Mandatory when using RSA signature method;UnionPay Signature Public Key Certificate is filled in this field" |
Filed name | Identifier | Type | Length | Request | Default value | 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 | |||
Reserved field | reserved | ANS | 1-2048 | C:Conditional | Please refer to reserved field definition for details | ||
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 | Returned based on configuration. If product type is Merchant-hosted , ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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. | ||
Card-Present transaction information field | cardTransData | ANS | 1-2048 | C:Conditional | Applied for card-present transactions. Please refer to 4.5.5 for details.Return sub-field IC card data ICCardData only in response message. | ||
Public key certificate for Signature | signPubKeyCert | AN | 2048 | C:Conditional | Return UnionPay public key certificate for signature when RSA is used as signature method |
Field name | Identifier | Type | Length | Request | Default value | 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 | 000802: AM remote payment | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 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. |
Filed name | Identifier | Type | Length | Request | Default value | 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 | Returned based on configuration. If product type is Merchant-hosted , ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
Public key certificate for Signature | signPubKeyCert | AN | 2048 | C:Conditional | Return UnionPay public key certificate for signature when RSA is used as signature method |
Field name | Identifier | Type | Length | Request | Default value | 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 | 000802: AM remote payment | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 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/MOTO/Recurring 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. |
Filed name | Identifier | Type | Length | Request | Default value | 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/MOTO/Recurring 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 /MOTO/Recurring 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 | |||
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 | Returned based on configuration. If product type is Merchant-hosted , ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
Public key certificate for Signature | signPubKeyCert | AN | 2048 | C:Conditional | Return UnionPay public key certificate for signature when RSA is used as signature method |
Field name | Identifier | Type | Length | Request | Default value | Note | |
---|---|---|---|---|---|---|---|
Version number | version | NS | 5 | M:Mandatory | 5.1.0 | ||
Encoding | encoding | ANS | 1-20 | M:Mandatory | UTF-8 | ||
Certificate ID | certId | N | 1-128 | M:Mandatory | |||
Signature | signature | ANS | 1-1024 | M:Mandatory | |||
Signature method | signMethod | N | 2 | M:Mandatory | 01: RSA | ||
Transaction type | txnType | N | 2 | M:Mandatory | 02 | ||
Transaction sub-type | txnSubType | N | 2 | M:Mandatory | 01: pre-authorization | ||
Product type | bizType | N | 6 | M:Mandatory | 000802 | 000802: AM remote payment | |
Channel type | channelType | N | 2 | M:Mandatory | 08 | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Back-end notification address | backUrl | ANS | 1-256 | M:Mandatory | Used in the back-end notification of merchant’s result; if sent, the merchant’s back-end transaction result notification will be sent. If the notification is sent by leased lines, a prefix should be added in front of the notification address: Initials of the leased lines plus a vertical line, ZX| | ||
Acquirer code | acqInsCode | AN | 8-11 | M:Mandatory | To be sent when the access type is Acquirer Access | ||
Merchant code | merId | AN | 15 | M:Mandatory | |||
Merchant category | merCatCode | N | 4 | M:Mandatory | Fill in MCC code, to be sent when the access type is Acquirer Access | ||
Merchant name | merName | ANS | 1-40 | M:Mandatory | To be sent when the access type is Acquirer Access | ||
Merchant abbreviation | merAbbr | ANS | 1-8 | M:Mandatory | To be sent when the access type is Acquirer Access | ||
Merchant order No | orderId | AN | 8-40 | M:Mandatory | Pre-authorized order No., generated by merchants | ||
Sending time of orders | txnTime | N | M:Mandatory | Format:YYYYMMDDhhmmss Format: YYYYMMDDhhmmss | |||
Account no | accNo | AN | 1-1024 | M:Mandatory | DPAN (Apple Pay token) | ||
Transaction amount | txnAmt | N | 1-12 | M:Mandatory | |||
Transaction currency | currencyCode | AN | 3 | M:Mandatory | |||
Bankcard verification info and ID info | customerInfo | ANS | 1-1024 | C:Conditional | "(1) Mainly fill in the cardholder's name (paymentData->data->cardholderName in PassKitApi) and payment password (paymentData->data-> encryptedPINData in PassKitApi) (2) Do not send if there is no returning in PassKitApi " | ||
Requestor reserved field | reqReserved | ANS | 1-1024 | O:Optional | Merchants will define the reserved field by themselves, which will be sent back as it is at transaction response | ||
Card transaction information field | cardTransData | ANS | 1-2048 | M:Mandatory | "Card transaction information field. Fill in ICCardData (paymentData->data-> paymentData-> emvData in PassKitApi) and carrierTp=6 and carrierAppTp=2" |
Filed name | Identifier | Type | Length | Request | Default value | Note | |
---|---|---|---|---|---|---|---|
Version number | version | NS | 5 | R:Returned | |||
Encoding | 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 code | acqInsCode | AN | 8-11 | C:Conditional | |||
Merchant code | merId | AN | 15 | R:Returned | |||
Merchant order No | orderId | AN | 8-40 | R:Returned | |||
Sending time of orders | txnTime | N | R:Returned | Format:YYYYMMDDhhmmss 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 | |||
Transaction query number | queryId | AN | 21 | M:Mandatory | Trace number of pre-authorized transactions for future query | ||
Response code | respCode | AN | 2 | M:Mandatory | |||
Response message | respMsg | ANS | 1-256 | M:Mandatory | |||
signPubKeyCert | signPubKeyCert | AN | 2048 | M:Mandatory | "Mandatory when using RSA signature method;UnionPay Signature Public Key Certificate is filled in this field" |
Filed name | Identifier | Type | Length | Request | Default value | 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 | Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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. | ||
Card-Present transaction information field | cardTransData | ANS | 1-2048 | C:Conditional | Applied for card-present transactions. Please refer to 4.5.5 for details.Return sub-field IC card data ICCardData only in response message. | ||
Public key certificate for Signature | signPubKeyCert | AN | 2048 | C:Conditional | Return UnionPay public key certificate for signature when RSA is used as signature method |
Field name | Identifier | Type | Length | Request | Default value | 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 | 000802: AM remote payment | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 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. |
Filed name | Identifier | Type | Length | Request | Default value | 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 | Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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 |
Field name | Identifier | Type | Length | Request | Default value | 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 | 000802: AM remote payment | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 | Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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 |
Field name | Identifier | Type | Length | Request | Default value | 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 | 000802: AM remote payment | ||
Access type | accessType | N | 1 | M:Mandatory | 1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 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 | 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. |
Filed name | Identifier | Type | Length | Request | Default value | 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 |
Filed name | Identifier | Type | Length | Request | Default value | 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 | Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment. | ||
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 |
SDK Version | Operating Environment |
JAVA | Eclipse+ jdk1.6.12u5 and above + Tomcat 6.0 and above |
.NET | Visual studio 2010 and above + .NET framework 4.0 and above |
PHP | php 5.3 and above |
Step 1 – Certificate Application
Developers need to obtain three certificates – signature certificate, sensitive information encryption certificate and signature verification certificate before calling the interface.
● Signature Certificate
Signature Certificate is used to sign or verify a transaction message. First create a message digest, and then use the digest to sign or verify the message.
How to get signature certificate
1) For signature certificate of the testing environment - It can be obtained from ‘assets’ directory in the SDK directly.
2) For signature certificate of the production environment - UnionPay Business Operation Centre will send an email to the contacts in the application form after approval. The required serial number and license key will be presented in the email.
● Signature Verification Certificate
Signature Verification Certificate is used to verify a transaction response
How to get signature verification certificate
1) For UPOP 5.0 signature verification certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.
2) For UPOP 5.0 signature verification certificate of the production environment - It can be obtained from ‘assets’ directory in the SDK directly.
3) For UPOP 5.1 signature verification certificate of the testing environment – It is carried in the UPOP reply message.
4) For UPOP 5.1 signature verification certificate of the production environment – It is carried in the UPOP reply message.
● Encryption Certificate
Encryption Certificate is used to encrypt the sensitive information in the UPOP request message.
How to get encryption certificate
1) For UPOP 5.0 encryption certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.
2) For UPOP 5.0 encryption certificate of the production environment –It can be obtained from ‘assets’ directory in the SDK directly.
3) For UPOP 5.1 encryption certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.
4) For UPOP 5.1 encryption certificate of the production environment – Merchant imitates inquiry message to UPOP system periodically (one time per day) to retrieve public key certificate update information. During encryption public key certificate updates, the UPOP system supports both new and old certificates, which last for one month. The UPOP system will return the latest encryption public key certificate and merchant server will replace it with local certificate.
Step 2 – SDK Integration and Configuration
To access the UPOP5.0/5.1 interface, we provide back-end SDKs of JAVA, PHP and .NET which package the fundamental functions such as signature & signature verification, HTTP interface request, etc. Please download the SDK of corresponding language and introduce it to your project.
Notice:
1)The final payment result must subject to the back-end notification from transaction inquiry interface.
2) The back-end notification received by the acquirer/gateway system must pass the signature verification to ensure its validity. To learn more about the verification method, please refer to the notification.
3) After receiving back-end notification and passing signature verification, please send transaction inquiry request for transaction result according to 'orderId', 'txnTime', 'merId' in the notification.
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 |