By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >Online Payments >Card Not Present Payment for Issuer
Card Not Present Payment for Issuer
Online Payments Issuer
Card Not Present Payment (CNP in short) for Issuer's Backend system provides an easy, flexible and secure solution for issuers to authorize UnionPay CNP transactions, including E-commerce, MO/TO, Recurring, etc.
Sandbox Testing
API Introduction
API Introduction
What is it?

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.

Key Features

Flexible

Supporting both internet and leased line connection.


Secure

Supported by well-developed security mechanism. 


When to Use it?

Card issuing bank with internet access

Who Use it?
Issuer Partners who wants to launch UnionPay CNP business fast, easily and securely.
Where to Use it?
This API is available globally except for mainland China.
Flow Chart
Flow Chart

流程图.png

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.
API Reference
API Reference
  • ISSUER_PURCHASE
  • ISSUER_PREAUTH
  • ISSUER_PREAUTH_COMPLETION_REQUEST
  • ISSUER_PREAUTH_COMPLETION_ ADVICE
  • ISSUER_CANCELLATION
  • ISSUER_REFUND
Interface description
ISSUER_PURCHASE API is used for purchase transaction that goods or services are delivered to consumers.
Request Method
HTTP POST
Request Parameter
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
Primary Account Number pan AN 1-19 M:Mandatory "6211110000000001234" The "pan" can be the card number or a token representing the Cardholder account.
PAN Expiry Date panExpiryDate N 4 C:Conditional "2203" Expiration date of the account number or token in YYMM format.
CNP Check Value cvn2 N 3 O:Optional “123”
Cardholder Name cardholderName S 1-30 C:Conditional "Jon Snow" Present if it is required by business.
Mobile Number cardholderMobileNo ANS 1-25 C:Conditional "86-123456789100" Present if it is required by business.
OTP Value otpValue ANS 40 C:Conditional For the Issuer Send SMS Mode, the "otpValue" shall be present in the authorization message. The format of OTP is ans40, with the first 20 bytes used to store the OTP key value, which is submitted by the Acquirer, and the last 20 bytes used to store the OTP.
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
Discount Amount discountAmt ANS 1-13 C:Conditional “20” The amount of discount, which could be displayed to the cardholder in the message sent from Unionpay to the Issuer.
Discount Note discountNote ANS 1-50 C:Conditional “Uplan discount” The note of discount, which could be displayed to the cardholder in the message sent from Unionpay to the Issuer.
Original Amount originalAmount ANS 1-13 C:Conditional “131.10” The original amount, which could be displayed to the cardholder in the message sent from Unionpay to the Issuer.
Cost Amount costAmount ANS 1-13 C:Conditional “101.10”　 The cost amount after the discount, indicating the amount the Cardholder actually pays for the transaction when a promotion is involved. 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 cost amount could be displayed to the cardholder in the message sent from Unionpay to the Issuer.
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
Electronic Commerce Indicator eci N 2 C:Conditional “05” Valid Values: “05” –The issuer has authenticated the cardholder successfully through UnionPay 3-D Secure authentication service; “06” –Merchant has attempted to authenticate the cardholder, and the UnionPay Attempts Service has responded on behalf of the Issuer. “07” –Authentication could not be performed due to technical or other problems. “09” –Issuer Authentication Mode in card-not-present self-service transactions. “10” –Issuer Non-Authentication Mode in card-not-present self-service transaction.
Authentication Value authValue ANS 28 C:Conditional Present if ECI value of 05, 06
Authentication ID authTrxID ANS 36 C:Conditional “f25084f0-5b16-4c0a-ae5d-b24808a95e4b” Present if ECI value of 05, 06, 07
Order Number orderNumber ANS 40 C:Conditional
QRC Information qrcInfo Object C:Conditional
QRC Use Case qrcuseInd ANS 3 C:Conditional
QRC Voucher Number qrcVoucherNo ANS 1-20 C:Conditional "1234567890123456789"
C2B Payment Code c2bCode ANS 1-34 C:Conditional Generated by UnionPay system. The payment index is unique permanently. It is used to locate a transaction. Present if it is a QRC-based transaction.
Wallet ID 1 walletID1 AN 8 C:Conditional "00010344" The information contained in the Consumer-presented QRC. Present if it is a QRC-based transaction.
Wallet ID 2 walletID2 AN 8 C:Conditional "00010344" The distinctive value associated to payer’s wallet. Present if it is a QRC-based transaction.
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
Token Information Verification Indicator tokenVerifyIndicator AN 1 C:Conditional "tokenVerifyIndicator" Token Information Verification Indicator
Token token AN 1-19 C:Conditional Token generated by the TSP. Present if it is a token-related transaction.
Token tokenExpiryDate AN 4 C:Conditional The expiry date of a Token that is generated by the TSP. Present if it is a token-related transaction.
Token Assurance Level tokenAssuranceLevel AN 1-2 C:Conditional Present if it is a token-related transaction. The Token Assurance Level is defined by the TSP based on the risk assessment. Valid Values: 0 to 99
Token tokenDomainID N 2 C:Conditional The Token Domain Identification indicates the application scenarios which are provided by the TR. Valid Values: 01: SE; 02: HCE; 03: QR Code; 04: Card-On-File (COF); 05: Digital wallet; 06: Chip or Magstripe Card. Present if it is a token-related transaction.
TRID trID AN 8-11 C:Conditional TRID is a unique number assigned by the TSP during TR Registration. Present if it is a token-related transaction.
Product Category productCate ANS 1 C:Conditional The Product Category is provided by the TR during Token Request. UnionPay system will de-tokenize the transaction and forward to the Issuer with this value in a Payment Token Transaction. Valid Values: 1: Mobile Payment. Present if it is a token-related transaction.
Product Sub-category productSubCate B 24 C:Conditional Binary form of data. The 10th-12th bytes of 9F63. For the definition of 9F63, please refer to UnionPay Integrated Circuit Card Specifications. Present if it is a token-related transaction.
Risk Information riskInfo Object O:Optional
Device ID  deviceID ANS 1-64 O:Optional The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile. It is present if mobile device is used to initiate the transaction.
GPS gps ANS 1-64 O:Optional "+37.12/-121.23" Components: +(-) latitude/+(-) longitude
SIM Card simCard Array 1-200 O:Optional The mobile number of the SIM cards. The mobile phone may have more than one SIM card. Format: Country code (1-3 digits) + “-” + subscriber number
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device
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”
Synchronous Response parameters
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
PAN Expiry Date panExpiryDate N 4 M:Mandatory "2203" Expiration date of the account number or token in YYMM format.
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
Response Code responseCode AN 2 M:Mandatory "00" It contains a code that defines the response to a request. Refer to the Response Code and Message for the valid values.
Response Message responseMsg S 1-100 M:Mandatory "Approved" It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed by the Merchant to notify the consumer of the payment outcome. Refer to the Response Code and Message for details.
Error Details errorDetail S 1-255 O:Optional “The Issuer response is time out.” It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.
Security Requirement
Security Requirement


UnionPay International has adopted unified security requirement, please refer to UPI Server-based API General Requirements  for signature and encryption guide.
Sequence Chart
Sequence Chart

1. CNP Purchase

时序图-purchase.png

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

时序图-purchase cacellation.png

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

时序图-pre-auth.png


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.
Steps to Launch
Steps to Launch

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
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2023. All rights reserved