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
Traditionally issuers use 8583 format interface for UnionPay CNP transaction authorization, which is time-consuming to develop and maintain. UPI CNP Issuing Backend Interface, which uses JSON message format, serves as an easy and friendly alternative to 8583 interface.
Flexible
Supporting both internet and leased line connection.
Secure
Supported by well-developed security mechanism.
Card issuing bank with internet access
1. Acquirer initiates card-not-present transaction (E-commerce, MO/TO, recurring) to UPI system.
2. UPI system transfers the authorization request to issuer (in JSON format).
3. Issuer authorizes the transaction and responds to UPI (in JSON format).
4. UPI transfers transaction response to acquirer.
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | M:Mandatory | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | M:Mandatory | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | M:Mandatory | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the Acquirer, this field shall be filled in with Acquirer IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PF ID | pfID | AN | 8 | C:Conditional | "00000111" | Present if it is a PF transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | M:Mandatory | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) ID | sdwID | AN | 8 | C:Conditional | "00010344" | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) Name | sdwName | ANS | 25 | C:Conditional | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | M:Mandatory | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Card Information Capture Method | captureMethod | N | 2 | M:Mandatory | “01” | Valid Values: • “00”: UNKNOWN; • “01”: MANUAL; • “03”: CONSUMER_PRESENTED_QRC(chip information included); • “04”: CONSUMER_PRESENTED_QRC(chip information excluded); • “05”: CONTACT; • “07”: NFC; • “10”: STORED_CREDENTIALS; • “93”: MERCHANT_PRESENTED_QRC(chip information included); • “94”: MERCHANT_PRESENTED_QRC(chip information excluded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional Card Information Capture Method | addcaptureMethod | N | 2 | M:Mandatory | “00” | Valid Values: • “00”: UNKNOWN; • “06”: PRE-AUTHORIZATION; • “08”: MO/TO ISSUER_PURCHASE; • “18”: MO/TO PRE-AUTHORIZATION; • “28”: RECURRING; • “64”: INSTALLMENT PAYMENT | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Terminal Type | terminalType | N | 2 | M:Mandatory | “08” | Valid Values: “03”: POS; “07”: PC; “08”: MOBILE; Reserved Values: “00”: UNKNOWN | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Initiation Mode | trxintMethod | N | 1 | M:Mandatory | Valid Values: • “0”: UNKNOWN; • “1”: ATTENDED. It is used to indicate transactions are initiated on attended terminals; • “2”: UNATTENDED. It indicates transactions initiated by cardholders at unattended terminals such as multimedia terminals, etc; • “3”: AGENT. It indicates transactions initiated by Merchant on cardholder’s behalf who is not present, like recurring, MO/TO.; • “4”: BATCH AGENT. It indicates all kinds of agent transactions that are initiated by Merchant in batch on cardholder’s behalf, who is not present, like batch recurring, batch MO/TO; • “5”: DEFERRED ONLINE ; AUTHORIZATION, UNATTENDED. It indicates deferred online authorizations initiated by cardholders at unattended terminals such as subway gates and car park gates, etc; • “6”: DEFERRED ONLINE AUTHORIZATION, ATTENDED. Cardholders and Merchant cashiers or bank employees at counter complete the transaction face-to-face first, but the online message is sent later. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | M:Mandatory | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | M:Mandatory | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Fee Amount | trxFeeAmt | ANS | 1-13 | C:Conditional | "1.10" | The tip or the convenience fee. Present if the Tip or Convenience Fee exists | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Discount Detail | discountDetail | Object | C:Conditional | The detail of discount. The discount information could be displayed to the cardholder in the message sent from Unionpay to the Issuer. Present if the discount exists | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Merchant ID | merchantID | ANS | 1-15 | M:Mandatory | “ABCDE01” | The distinctive value associated to the Merchant. The value must uniquely identify any Merchant of the UNIONPAY API. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | M:Mandatory | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Country Code | merchantCountry | N | 3 | M:Mandatory | "156" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Name | merchantName | ANS | 1-25 | M:Mandatory | "UnionPay International" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | C:Conditional | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
QRC Information | qrcInfo | Object | C:Conditional | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Payment Reference Number (PAR) | par | 29 | C:Conditional | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. Present if it exists. The distinctive value associated to payee’s wallet. Present if it is a QRC-based transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | C:Conditional | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Risk Information | riskInfo | Object | O:Optional | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Settlement Date | settlementDate | N | 4 | M:Mandatory | "1230" | Format:MMDD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Currency | settlementCurrency | N | 3 | C:Conditional | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates UNIONPAY API’s settlement currency. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Amount | settlementAmt | ANS | 1-13 | C:Conditional | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Conversion Rate | settlementConvRate | ANS | 1-9 | C:Conditional | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Currency | cardholderBillingCurrency | N | 3 | C:Conditional | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Amount | cardholderBillingAmt | ANS | 1-13 | C:Conditional | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Conversion Rate | cardholderBillingConvRate | ANS | 1-9 | C:Conditional | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conversion Date | conversionDate | N | 4 | C:Conditional | "1230" | Present if either "settlementAmt" or “cardholderBillingAmt”exists. Format: MMDD | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PIN Data | pinData | B | 64 | C:Conditional | Filled with the cipher text of PIN, which contains 64 bits binary data. PIN in ANSIX9.8 format (with PAN) is encrypted with PIN encryption key. Present if it is required by business. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PIN Encryption Algorithm | pinEncryptAlg | N | 1 | C:Conditional | “6” | Filled with the digital encryption algorithm to encrypt the PIN. Present when “pinData” exists. Valid value: “6”: “Double length 3DES algorithm” |
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | R:Returned | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Encrypted Data | encData | Object | M:Mandatory | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||
|
Authorization Identification Response | authCode | AN | 6 | O:Optional | Authorization Identification Response | The authorization code for the approved transaction assigned by the Issuer. | ||||||||||||||||||||||||
Message Response | msgResponse | Object | M:Mandatory | ||||||||||||||||||||||||||||
|
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | M:Mandatory | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | M:Mandatory | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | M:Mandatory | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PF ID | pfID | AN | 8 | C:Conditional | "00000111" | Present if it is a PF transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | M:Mandatory | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) ID | sdwID | AN | 8 | C:Conditional | "00010344" | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) Name | sdwName | ANS | 25 | C:Conditional | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | M:Mandatory | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Card Information Capture Method | captureMethod | N | 2 | M:Mandatory | ”01” | Valid Values: • “00”: UNKNOWN; • “01”: MANUAL; • “03”: CONSUMER_PRESENTED_QRC(chip information included); • “04”: CONSUMER_PRESENTED_QRC(chip information excluded); • “05”: CONTACT; • “07”: NFC; • “10”: STORED_CREDENTIALS; • “93”: MERCHANT_PRESENTED_QRC(chip information included); • “94”: MERCHANT_PRESENTED_QRC(chip information excluded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional Card Information Capture Method | addcaptureMethod | N | 2 | M:Mandatory | “00” | Valid Values: • “00”: UNKNOWN; • “06”: Pre-authorization; • “18”: MO/TO Pre-authorization | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Terminal Type | terminalType | N | 2 | M:Mandatory | “08” | Valid Values: “03”: POS; “07”: PC; “08”: MOBILE; Reserved Values: “00”: UNKNOWN | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Initiation Mode | trxintMethod | N | 1 | M:Mandatory | “0” | Valid Values: • “0”: UNKNOWN; • “1”: ATTENDED. It is used to indicate transactions are initiated on attended terminals. • “2”: UNATTENDED. It indicates transactions initiated by cardholders at unattended terminals such as multimedia terminals, etc. • “3”: AGENT. It indicates transactions initiated by Merchant on cardholder’s behalf who is not present, like recurring, MO/TO. • “4”: BATCH AGENT. • “5”: DEFERRED ONLINE AUTHORIZATION, UNATTENDED. It indicates deferred online authorizations initiated by cardholders at unattended terminals such as subway gates and car park gates, etc. • “6”: DEFERRED ONLINE AUTHORIZATION, ATTENDED. Cardholders and Merchant cashiers or bank employees at counter complete the transaction face-to-face first, but the online message is sent later. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | M:Mandatory | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | M:Mandatory | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Discount Detail | discountDetail | Object | C:Conditional | The detail of discount. The discount information could be displayed to the cardholder in the message sent from Unionpay to the Issuer. Present if the discount exists | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Merchant ID | merchantID | ANS | 1-15 | M:Mandatory | “ABCDE01” | The distinctive value associated to the Merchant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | M:Mandatory | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Country Code | merchantCountry | N | 3 | M:Mandatory | "156" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Name | merchantName | ANS | 1-25 | M:Mandatory | "UnionPay International" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | C:Conditional | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Cardholder Billing Currency | cardholderBillingCurrency | N | 3 | C:Conditional | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Amount | cardholderBillingAmt | ANS | 1-13 | C:Conditional | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Conversion Rate | cardholderBillingConvRate | ANS | 1-9 | C:Conditional | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
QRC Information | qrcInfo | Object | C:Conditional | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Payment Reference Number (PAR) | par | AN | 29 | C:Conditional | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | C:Conditional | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Risk Information | riskInfo | Object | O:Optional | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
PIN Data | pinData | B | 64 | C:Conditional | Filled with the cipher text of PIN, which contains 64 bits binary data. PIN in ANSIX9.8 format (with PAN) is encrypted with PIN encryption key. Present if it is required by business. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PIN Encryption Algorithm | pinEncryptAlg | N | 1 | C:Conditional | “6” | Filled with the digital encryption algorithm to encrypt the PIN. Valid value: “6”: “Double length 3DES algorithm”. Present when “pinData” exists. |
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | R:Returned | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Encrypted Data | encData | Object | M:Mandatory | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||
|
Authorization Identification Response | authCode | AN | 6 | C:Conditional | “000000” | The authorization code for the approved transaction assigned by the Issuer. This field shall be present if Response Code indicates that the transaction request is authorized, and the combined set of "authCode", "pan", and “merchantID” must be unique before transaction settlement. | ||||||||||||||||||||||||
Message Response | msgResponse | Object | M:Mandatory | ||||||||||||||||||||||||||||
|
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | None | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | None | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Original Message ID | originalMsgID | AN | 37 | None | "U0001034420171230235959000000" | When it is used to cancel purchase transaction, the value shall be the “msgID” value of the ISSUER_PURCHASE. When it is used to cancel pre-authorization transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH. When it is used to cancel pre-authorization completion transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH_COMPLETION. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | None | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Card Information Capture Method | captureMethod | N | 2 | None | ”01” | Valid Values: • “00”: UNKNOWN; • “01”: MANUAL; • “03”: CONSUMER_PRESENTED_QRC(chip information included); • “04”: CONSUMER_PRESENTED_QRC(chip information excluded); • “05”: CONTACT; • “07”: NFC; • “10”: STORED_CREDENTIALS; • “93”: MERCHANT_PRESENTED_QRC(chip information included); • “94”: MERCHANT_PRESENTED_QRC(chip information excluded) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional Card Information Capture Method | addcaptureMethod | N | 2 | None | “00” | Valid Values: • “00”: UNKNOWN; • “06”: Pre-authorization; • “18”: MO/TO Pre-authorization | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Authorization Identification Response | authCode | AN | 6 | None | “000000” | The authorization code for the approved transaction assigned by the Issuer. This field shall be present if Response Code indicates that the transaction request is authorized, and the combined set of "authCode", "pan", and “merchantID” must be unique before transaction settlement. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Initiation Mode | trxintMethod | N | 1 | None | “0” | Valid Values: • “0”: UNKNOWN; • “1”: ATTENDED. It is used to indicate transactions are initiated on attended terminals. • “2”: UNATTENDED. It indicates transactions initiated by cardholders at unattended terminals such as multimedia terminals, etc. • “3”: AGENT. It indicates transactions initiated by Merchant on cardholder’s behalf who is not present, like recurring, MO/TO. • “4”: BATCH AGENT. • “5”: DEFERRED ONLINE AUTHORIZATION, UNATTENDED. It indicates deferred online authorizations initiated by cardholders at unattended terminals such as subway gates and car park gates, etc. • “6”: DEFERRED ONLINE AUTHORIZATION, ATTENDED. Cardholders and Merchant cashiers or bank employees at counter complete the transaction face-to-face first, but the online message is sent later. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | None | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | None | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Discount Detail | discountDetail | Object | None | The detail of discount. The discount information could be displayed to the cardholder in the message sent from Unionpay to the Issuer. Present if the discount exists | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Merchant ID | merchantID | ANS | 1-15 | None | “ABCDE01” | The distinctive value associated to the Merchant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | None | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Country Code | merchantCountry | N | 3 | None | "156" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Name | merchantName | ANS | 1-25 | None | "UnionPay International" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | None | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Settlement Date | settlementDate | N | 4 | None | "1230" | Format:MMDD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Currency | settlementCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates UNIONPAY API’s settlement currency. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Amount | settlementAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Conversion Rate | settlementConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Currency | cardholderBillingCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Amount | cardholderBillingAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Conversion Rate | cardholderBillingConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conversion Date | conversionDate | N | 4 | None | "1230" | Present if either "settlementAmt" or “cardholderBillingAmt”exists. Format: MMDD | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Payment Reference Number (PAR) | par | AN | 29 | None | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | None | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Risk Information | riskInfo | Object | None | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
PIN Data | pinData | B | 64 | None | Filled with the cipher text of PIN, which contains 64 bits binary data. PIN in ANSIX9.8 format (with PAN) is encrypted with PIN encryption key. Present if it is required by business. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PIN Encryption Algorithm | pinEncryptAlg | N | 1 | None | “6” | Filled with the digital encryption algorithm to encrypt the PIN. Valid value: “6”: “Double length 3DES algorithm”. Present when “pinData” exists. |
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||
|
Message Response | msgResponse | Object | None | |||||||||||||||||||||||||||
|
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | None | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | None | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Original Message ID | originalMsgID | AN | 37 | None | "U0001034420171230235959000000" | When it is used to cancel purchase transaction, the value shall be the “msgID” value of the ISSUER_PURCHASE. When it is used to cancel pre-authorization transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH. When it is used to cancel pre-authorization completion transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH_COMPLETION. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | None | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Card Information Capture Method | captureMethod | N | 2 | None | ”01” | Valid Values: • “00”: UNKNOWN; • “01”: MANUAL; • “03”: CONSUMER_PRESENTED_QRC(chip information included); • “04”: CONSUMER_PRESENTED_QRC(chip information excluded); • “05”: CONTACT; • “07”: NFC; • “10”: STORED_CREDENTIALS; • “93”: MERCHANT_PRESENTED_QRC(chip information included); • “94”: MERCHANT_PRESENTED_QRC(chip information excluded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional Card Information Capture Method | addcaptureMethod | N | 2 | None | “00” | Valid Values: • “00”: UNKNOWN; • “06”: Pre-authorization; • “18”: MO/TO Pre-authorization | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Authorization Identification Response | authCode | AN | 6 | None | “000000” | The authorization code for the approved transaction assigned by the Issuer. This field shall be present if Response Code indicates that the transaction request is authorized, and the combined set of "authCode", "pan", and “merchantID” must be unique before transaction settlement. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Initiation Mode | trxintMethod | N | 1 | None | “0” | Valid Values: • “0”: UNKNOWN; • “1”: ATTENDED. It is used to indicate transactions are initiated on attended terminals. • “2”: UNATTENDED. It indicates transactions initiated by cardholders at unattended terminals such as multimedia terminals, etc. • “3”: AGENT. It indicates transactions initiated by Merchant on cardholder’s behalf who is not present, like recurring, MO/TO. • “4”: BATCH AGENT. • “5”: DEFERRED ONLINE AUTHORIZATION, UNATTENDED. It indicates deferred online authorizations initiated by cardholders at unattended terminals such as subway gates and car park gates, etc. • “6”: DEFERRED ONLINE AUTHORIZATION, ATTENDED. Cardholders and Merchant cashiers or bank employees at counter complete the transaction face-to-face first, but the online message is sent later. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | None | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | None | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Discount Detail | discountDetail | Object | None | The detail of discount. The discount information could be displayed to the cardholder in the message sent from Unionpay to the Issuer. Present if the discount exists | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Merchant ID | merchantID | ANS | 1-15 | None | “ABCDE01” | The distinctive value associated to the Merchant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | None | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Country Code | merchantCountry | N | 3 | None | "156" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Name | merchantName | ANS | 1-25 | None | "UnionPay International" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | None | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Settlement Date | settlementDate | N | 4 | None | "1230" | Format:MMDD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Currency | settlementCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates UNIONPAY API’s settlement currency. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Amount | settlementAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Conversion Rate | settlementConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Currency | cardholderBillingCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Amount | cardholderBillingAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Conversion Rate | cardholderBillingConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conversion Date | conversionDate | N | 4 | None | "1230" | Present if either "settlementAmt" or “cardholderBillingAmt”exists. Format: MMDD | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Payment Reference Number (PAR) | par | AN | 29 | None | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | None | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Risk Information | riskInfo | Object | None | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
PIN Data | pinData | B | 64 | None | Filled with the cipher text of PIN, which contains 64 bits binary data. PIN in ANSIX9.8 format (with PAN) is encrypted with PIN encryption key. Present if it is required by business. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PIN Encryption Algorithm | pinEncryptAlg | N | 1 | None | “6” | Filled with the digital encryption algorithm to encrypt the PIN. Valid value: “6”: “Double length 3DES algorithm”. Present when “pinData” exists. |
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||
|
Message Response | msgResponse | Object | None | |||||||||||||||||||||||||||
|
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | None | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | None | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | None | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Original Message ID | originalMsgID | AN | 37 | None | "U0001034420171230235959000000" | When it is used to cancel purchase transaction, the value shall be the “msgID” value of the ISSUER_PURCHASE. When it is used to cancel pre-authorization transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH. When it is used to cancel pre-authorization completion transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH_COMPLETION. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Authorization Identification Response | authCode | AN | 6 | None | “000000” | This field shall be present if it is present in the response message of original transaction. The value of this field shall be obtained from the response message of the original transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | None | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. The value is the same as the original transaction amount. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | None | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant ID | “merchantID” | ANS | 1-15 | None | “ABCDE01” | The distinctive value associated to the Merchant. The value must uniquely identify any Merchant of the UNIONPAY API. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | None | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | None | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
QRC Information | qrcInfo | Object | None | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Payment Reference Number (PAR) | par | AN | 29 | None | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | None | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Message Response | msgResponse | Object | None | ||||||||||||||||||||||||||||
|
Field name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Acquirer IIN | acquirerIIN | AN | 8 | None | "00010344" | The distinctive value associated to the Acquirer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Forwarding IIN | forwardingIIN | AN | 8 | None | “00010344” | The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PF ID | pfID | AN | 8 | None | "00000111" | Present if it is a PF transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Local Transaction Date &Time | localTxnDateTime | N | 10 | None | Format: MMDDhhmmss | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) ID | sdwID | AN | 8 | None | "00010344" | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Staged Digital Wallet (SDW) Name | sdwName | ANS | 25 | None | For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Original Message ID | originalMsgID | AN | 37 | None | "U0001034420171230235959000000" | When it is used to cancel purchase transaction, the value shall be the “msgID” value of the ISSUER_PURCHASE. When it is used to cancel pre-authorization transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH. When it is used to cancel pre-authorization completion transaction, the value shall be the “msgID” value of the ISSUER_PREAUTH_COMPLETION. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Encrypted Data | encData | Object | None | Encrypted with the public key of the Encryption Certificate. JWE |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Authorization Identification Response | authCode | AN | 6 | None | “000000” | The authorization code for the approved transaction assigned by the Issuer. This field shall be present if Response Code indicates that the transaction request is authorized, and the combined set of "authCode", "pan", and “merchantID” must be unique before transaction settlement. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Amount | trxAmt | ANS | 1-13 | None | "101.10" | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705". The value must include the transaction fee amount if it exists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Transaction Currency | trxCurrency | N | 3 | None | "156" | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant ID | merchantID | ANS | 1-15 | None | “ABCDE01” | The distinctive value associated to the Merchant. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Category Code | mcc | N | 4 | None | Convenience store is represented by "5411". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Country Code | merchantCountry | N | 3 | None | "156" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Merchant Name | merchantName | ANS | 1-25 | None | "UnionPay International" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ecommerce Data | eComData | Object | None | e-Commerce transaction specific data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Settlement Date | settlementDate | N | 4 | None | "1230" | Format:MMDD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Currency | settlementCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates UNIONPAY API’s settlement currency. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Amount | settlementAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settlement Conversion Rate | settlementConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the " settlementCurrency " has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Currency | cardholderBillingCurrency | N | 3 | None | “840” | A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Amount | cardholderBillingAmt | ANS | 1-13 | None | “15.17” | The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Cardholder Billing Conversion Rate | cardholderBillingConvRate | ANS | 1-9 | None | "71212345" | The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Conversion Date | conversionDate | N | 4 | None | "1230" | Present if either "settlementAmt" or “cardholderBillingAmt”exists. Format: MMDD | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
QRC Information | qrcInfo | Object | None | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Payment Reference Number (PAR) | par | AN | 29 | None | Enables Merchants, Acquirers and Payment Processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying PAN. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Token Information | tokenInfo | Object | None | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Risk Information | riskInfo | Object | None | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Filed name | Identifier | Type | Length | Request | Default value | Note | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Message ID | msgID | AN | 37 | None | "U0001034420171230235959000000" | It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits) | |||||||||||||||||||||||||
Message Response | msgResponse | Object | None | ||||||||||||||||||||||||||||
|
UnionPay International has adopted unified security requirement, please refer to UPI Server-based API General Requirements for signature and encryption guide.
1. CNP Purchase
1.The UNIONPAY API submits ISSUER_PURCHASE request message to the Issuer system.
2.The Issuer system brings back the transaction outcome to the UNIONPAY API in the ISSUER_PURCHASE response message.
Exceptional flows:
1.When the UNIONPAY API does not receive the ISSUER_PURCHASE response message within 40 seconds, it can initiate ISSUER_REVERSAL message, using the Message ID of the ISSUER_PURCHASE to reversal the transaction.
2.The Issuer system will return the ISSUER_REVERSAL transaction outcome and settlement information to the UNIONPAY API.
2. CNP Purchase Cancellation
1.The UNIONPAY API submits ISSUER_CANCELLATION request message to the Issuer system, using the Message ID of ISSUER_PURCHASE to cancellation the CNP purchase.
2.The Issuer system checks if the original message exists. If not, the Issuer system will reject the transaction. If yes, it will bring back the transaction outcome to the UNIONPAY API in the ISSUER_CANCELLATION response message.
Exceptional flows:
1.When the UNIONPAY API does not receive the ISSUER_CANCELLATION response message within 40 seconds, it can initiate ISSUER_REVERSAL message, using the Message ID of the ISSUER_CANCELLATION to reversal the transaction.
2.The Issuer system returns the ISSUER_REVERSAL transaction result to the UNIONPAY API.
3. CNP Pre-authorization
1.The UNIONPAY API submits ISSUER_PREAUTH request message to the Issuer system.
2.The Issuer system forwards the payment request to the Issuer and brings back the transaction outcome to the UNIONPAY API in the ISSUER_PREAUTH response message.
Exceptional flows:
1.When the UNIONPAY API does not receive the ISSUER_PREAUTH response message within 40 seconds, it can initiate ISSUER_REVERSAL message, using the Message ID of the ISSUER_PREAUTH to reversal the transaction.
2.The Issuer system will return the ISSUER_REVERSAL transaction outcome to the UNIONPAY API.
If you are UPI issuer member, you need to fill in the Application Form of API Service Product with Terms and Conditions.
When the business goes online, the issuing bank shall conduct key exchange with UnionPay international to ensure the transaction security, and the card issuing bank shall submit system parameters such as IIN and API called address
Please contact Developer operation team by submitting order