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 >NFC Pre-Authorization Transaction for Issuer
NFC Pre-Authorization Transaction for Issuer
Online Payments Issuer
NFC Pre-Authorization Transaction provides an easy, flexible and secure solution for issuers to authorize NFC Pre-Authorization Transaction.
Sandbox Testing
API Introduction
API Introduction
What is it?

Traditionally issuers use 8583 format interface for UnionPay NFC transaction authorization, which is time-consuming to develop and maintain. NFC Pre-Authorization Transaction, which uses JSON message format, serves as an easy and friendly alternative to 8583 interface.

This API enables issuers to initiate and deal with NFC Pre-Authorization transaction.

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 that wants to launch NFC Pre-Authorization Transaction 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 NFC transaction 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_PREAUTH
  • ISSUER_PREAUTH_COMPLETION_REQUEST
  • ISSUER_PREAUTH_COMPLETION_ ADVICE
  • ISSUER_CANCELLATION
  • ISSUER_REVERSAL
  • ISSUER_REFUND
Interface description
ISSUER_PREAUTH API is used for requesting approval of transactions. Subsequent ISSUER_PREAUTH_COMPLETION API is required to enable the clearing and settlement of an approved transaction.
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 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
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” Present if it is required by business.
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"
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; • “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
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.
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
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
QRC Use Case Indicator qrcuseInd ANS 3 C:Conditional Valid values：100- Consumer-presented QRC, purchase transaction. 210- Merchant-presented QRC, purchase transaction. 211- Merchant-presented QRC, purchase transaction, debit card only. Example: purchasing financial products. 220- Merchant-presented QRC, ATM cash withdrawal. 212- Merchant-presented QRC, purchase transaction in small businesses. 231- P2P QRC-based Payment, primary credit transaction. 232- P2P QRC-based Payment, account funding transaction, Reserved. Present if it is a QRC-based transaction.
QRC Voucher Number qrcVoucherNo ANS 1-20 C:Conditional "1234567890123456789" 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.
C2B Payment Code c2bCode ANS 1-34 C:Conditional The information contained in the Consumer-presented QRC. Present if it is a QRC-based transaction.
Wallet ID 1 walletID1 AN 8 C:Conditional "00010344" The distinctive value associated to payer’s wallet. Present if it is a QRC-based transaction.
Wallet ID 2 walletID2 AN 8 C:Conditional "00010344" The distinctive value associated to payee’s wallet. Present if it is a QRC-based transaction.
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
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 Expiry Date 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 The Token Assurance Level is defined by the TSP based on the risk assessment. Valid Values: 0 to 99
Token Domain Identification 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 C:Conditional 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
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.
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 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
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.NFC Pre-authorization

时序图-pre-auth.png

1.The UNIONPAY API submits ISSUER_PREAUTH request message to the Issuer system.

2.The Issuer 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.


2. NFC Pre-authorization Cancellation

时序图-pre-auth Cancellation.png

1.The UNIONPAY API submits ISSUER_CANCELLATION request message to the Issuer system, using the Message ID of ISSUER_PREAUTH to cancellation the CNP pre-authorization.

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: 

3.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.

4.The Issuer system returns the ISSUER_REVERSAL transaction result to the UNIONPAY API.


3.NFC Pre-authorization Completion

时序图-pre-auth completion.png

1.The UNIONPAY API submits ISSUER_PREAUTH_COMPLETION_REQUEST request message to the Issuer system.

2.The Issuer system brings back the transaction outcome to the UNIONPAY API in the ISSUER_PREAUTH_COMPLETION_REQUEST response message. 

Exceptional flows: 

3.When the UNIONPAY API does not receive the ISSUER_PREAUTH_COMPLETION_REQUEST response message within 40 seconds, it can initiate ISSUER_REVERSAL message, using the Message ID of the ISSUER_PREAUTH_COMPLETION_REQUEST to reversal the transaction.

4.The Issuer system will return the ISSUER_REVERSAL transaction outcome to the UNIONPAY API.


4.NFC Pre-authorization Completion (Advice)

时序图-pre-auth completion advice.png

1.The UNIONPAY API submits ISSUER_PREAUTH_COMPLETION_ ADVICE request message to the Issuer system.

2.The Issuer system brings back the transaction outcome to the UNIONPAY API in the ISSUER_PREAUTH_COMPLETION_ADVICE response message. 

Exceptional flows: 

3.When the UNIONPAY API does not receive the ISSUER_PREAUTH_COMPLETION_ADVICE response message within 40 seconds, it will put the refund transaction in store-and-forward queue for storing and forwarding.

4.The Issuer system will return the ISSUER_PREAUTH_COMPLETION_ADVICE response to the UNIONPAY API.


5.NFC Pre-authorization Completion Cancellation

时序图-pre-auth completion cacellation.png

1.The UNIONPAY API submits ISSUER_CANCELLATION request message to the Issuer system, using the Message ID of ISSUER_PREAUTH_COMPLETION to cancellation the CNP pre-authorization completion.

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: 

3.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.

4.The Issuer system returns the ISSUER_REVERSAL transaction result to the UNIONPAY API.


6.NFC Refund

时序图-refund.png

1.The UNIONPAY API submits ISSUER_REFUND request message to the Issuer system.

2.The Issuer system will bring back the transaction outcome to the UNIONPAY API in the ISSUER_REFUND response message.  

Exceptional flows: 

3.When the UNIONPAY API does not receive the ISSUER_REFUND response message within 40 seconds, it will put the refund transaction in store-and-forward queue for storing and forwarding.

4.The Issuer system will return the ISSUER_REFUND response to the UNIONPAY API.

Note: When the Issuer receives repeated ISSUER_REFUND request message with the same Message ID, only one refund transaction will be involved in settlement.
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 - 2024. All rights reserved