The API is based on UninonPay Payment Control SDK (iOS). It contains the APP SDK and the back-end SDK. Merhcant APP shall invoke the APP SDK to complete purchase transaction. The APP SDK will collect payment information to complete the purchase transaction at the front-end. Other transactions are all back-end ones which can be done 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 (iOS) Payment can provide a convenient and secure channel for the cardholder to finish the payment within the merchant APP without re-direction. It supports SecurePay in-APP. The payment can be initiated by the merchant directly or by the gateway/acquirer via internet access.
UPI In-APP (iOS) Payment will be used to help merchant provide the payment service. And the UnionPay SDK will be resopnsible for securely collecting the payment information and completing transction.
1) In-APP Payment shall support puchase, inquiry and receiving back-end notification. Other transctions will be optional.
2) Merhcant APP shall invoke UnionPay SDK to complete purchase transaction. The SDK will collect payment information to complete the purchase transaction at the front-end. Other transactions are all back-end transactions which can be done via the back-end interface to UPOP5.0/5.1. Please note the differece between front-end transaction and back-end transaction while using the testing URL and the procution URL.
3) Certificate of testing environment is contained in the back-end SDK package.
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 | 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 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. |
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 | 0: Merchant direct access1: 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 transactionShould 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 | Required for Merchant-presented QRC PaymentUPOP will return QRC information and discount information (if any) to acquirers/merchant.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-12DD: 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 systemThis field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12DD: 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 | ||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04:Credit/Debit account05: Prepaid account | ||
Issuer institution identify mode | IssuerIdentifyMode | N | 1 | C:Conditional | Returned for purchase and pre-authorization transaction:0: Authentication mode1: 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 |
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 | 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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: Acquirer access | ||
Channel type | channelType | N | 2 | M:Mandatory | 08: Mobile | ||
Front-end URL | frontUrl | ANS | 1-256 | O:Optional | Applied to front-end transactionUsed for sending front-end notification to merchantDo not support invisible characters such as newlineNot required for QRC Payment | ||
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 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 purchase transaction,generated by merchantShould not contain ‘-’ and ‘_’In Merchant-presented QRC Payment, this value should be identical with Reference label in financial network data field of QRC | ||
Order time | txnTime | N | M:Mandatory | Time merchant sent transaction Format: YYYYMMDDhhmmss | |||
Transaction amount | txnAmt | N | 1-12 | M:Mandatory | According to the transaction currency, when the currency is RMB, the last two numbers on the right of the field should be included. When the currency is not RMB and does not have a decimal number, 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 | ||
Order timeout | payTimeout | N | C:Conditional | Applied to SecurePay Transactions where user payment succeeds but exceeds the time, merchant is not notified, system will automatically refund, to be returned to user account in around 5 working days.Required for QRC Payment. Format: YYYYMMDDhhmmss | |||
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. | ||
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 | ||
Order timeout | payTimeout | N | C:Conditional | Applied to SecurePay Transactions where user payment succeeds but exceeds the time, merchant is not notified, system will automatically refund, to be returned to user account in around 5 working days.Required for QRC Payment. Format: YYYYMMDDhhmmss | |||
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. |
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 | Required for Merchant-presented QRC PaymentUPOP will return QRC information and discount information (if any) to acquirers/merchant.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-12DD: 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-12DD: 1-31 Format: MMDD | |||
System Trace Audit Number | traceNo | N | 6 | M:Mandatory | |||
Transmission date and time | traceTime | N | M:Mandatory | Format: MMDDhhmmss | |||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04: Credit/Debit account05: 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 |
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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: 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 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 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-12DD: 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-12DD: 1-31 Format: MMDD | |||
System Trace Audit Number | traceNo | N | 6 | M:Mandatory | |||
Transmission date and time | traceTime | N | M:Mandatory | Format: MMDDhhmmss | |||
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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: 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 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 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.0 | 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.0 | 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-12DD: 1-31 Format: MMDD | |||
Settlement currency | settleCurrencyCode | AN | 3.0 | 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-12DD: 1-31 Format: MMDD | |||
System Trace Audit Number | traceNo | N | 6 | M:Mandatory | |||
Transmission date and time | traceTime | N | M:Mandatory | Format: MMDDhhmmss | |||
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 | 02: Pre-authorization | ||
Transaction sub-type | txnSubType | N | 2 | M:Mandatory | 01: Pre-authorization | ||
Product type | bizType | N | 6 | M:Mandatory | 000201: SecurePay | ||
Channel type | channelType | N | 2 | M:Mandatory | 08: Mobile | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: Acquirer access | ||
Front-end URL | frontUrl | ANS | 1-256 | O:Optional | Applied for front-end type transaction.Used for sending front-end notification to merchantDo not support invisible characters such as newline | ||
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 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 pre-authorization, generated by merchant.Should not contain ‘-’ and ‘_’ | ||
Order time | txnTime | N | M:Mandatory | Format: YYYYMMDDhhmmss | |||
Transaction amount | txnAmt | N | 1-12 | M:Mandatory | According to the transaction currency, when the currency is RMB, the last two numbers on the right of the field should be included. When the currency is not RMB and does not have a decimal number, 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. | ||
Order timeout | payTimeout | N | O:Optional | Applies to SecurePay Transactions where user payment succeeds but exceeds the time, merchant is not notified. System will automatically refund to the user account in around 5 working days. Format: YYYYMMDDhhmmss | |||
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 | |||
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 | |||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04: Credit/Debit account05: 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 |
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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: 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 accessDo not support invisible characters such as newline | ||
Merchant abbreviation | merAbbr | ANS | 1-8 | C:Conditional | Applied if access type is acquirer access8 Chinese characters or 8 charactersDo 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 | |||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04: Credit/Debit account05: 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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct access1: 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 accessDo not support invisible characters such as newline | ||
Merchant abbreviation | merAbbr | ANS | 1-8 | C:Conditional | Applied if access type is acquirer access8 Chinese characters or 8 charactersDo 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-12DD: 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-12DD: 1-31 Format: MMDD | |||
System Trace Audit Number | traceNo | N | 6 | M:Mandatory | |||
Transmission date and time | traceTime | N | M:Mandatory | Format: MMDDhhmmss | |||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04: Credit/Debit account05: 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 | 000201: SecurePay | ||
Access type | accessType | N | 1 | M:Mandatory | 0: Merchant direct 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 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 | ||
Secondary Merchant ID | subMerId | AN | 5-15 | C:Conditional | Applied upon platform type merchant access | ||
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-12DD: 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 | DD | C:Conditional | This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12DD: 1-31 Format: MMDD | ||
System Trace Audit Number | traceNo | N | 6 | M:Mandatory | |||
Transmission date and time | traceTime | N | M:Mandatory | Format: MMDDhhmmss | |||
Account attribute | payCardType | N | 2 | C:Conditional | Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04: Credit/Debit account05: 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 |
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
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 done the application process. 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 can be obtained from ‘assets’ directory in the SDK directly.
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 first and introduce it to your development project.
Notice:
1)Front-end notification can only be taken as reference, the final payment result must subject to the back-end notification from transaction inquiry interface.
2) The front-end/back-end notification received by the merchant system must pass the signature verification to ensure it is sent by UnionPay. The verification method please refers to the notification.
3) After receiving the front-end/back-end notification and passing the signature verification, send transaction inquiry request for the transaction result according to “orderId”, ”txnTime”, ”merId” in the notification.