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 >POS Pre-Authorization Transaction for Acquirer
POS Pre-Authorization Transaction for Acquirer
Online Payments Merchant Acquirer
POS Transaction API enables acquirers to be accepted to UnionPay network for POS businesses using message format in JSON other than ISO 8583.
Sandbox Testing
API Introduction
API Introduction
What is it?

POS Transaction API is steadily getting recognition from institutions for its satisfactory readability and scalability. In order to assist UPI members with POS businesses in an easier manner, UPI has enabled POS Transaction API with JSON message foramt.This API enable Acquirer to initiate and deal with POS Pre-Authorization transaction.

Key Features

Easier to develop.

Reduce development workload.


When to Use it?

When acquirers and merchants involve in UnionPay POS retail business, contactless transportation payment solutions.

Who Use it?
Acquirer Institutions who are unfamiliar with ISO 8583 and would like to launch POS business. Non financial institutions.
Where to Use it?
This API is available globally.
Flow Chart
Flow Chart

POS 流程图.png

1. Acquirer initiates POS transaction to UPI system.    (in JSON format).

2.UPI system forwards POS transaction request to issuer.

3.Issuer authorizes the transaction and responds to UPI.

4.UPI forwards transaction response to acquirer (in JSON format).
API Reference
API Reference
  • POS_PREAUTH
  • POS_PREAUTH_COMPLETION
  • VOID
  • REFUND
  • MSG_RESULT_INQUIRY
Interface description
The POS_PREAUTH API is used for requesting approval of transactions. Subsequent POS_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 "S00010340001034420171230235959000000" It is used to match a response to its request. The value must uniquely identify any message that the Acquirer initiates on any day. The value in the response must match the value in the request. Components: “S”+ 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.
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.
Payment Facilitator ID (PF ID) pfID AN 8 C:Conditional The Payment Facilitator ID assigned by UPI. It is present if the transaction is submitted by Merchants registered with the Payment Facilitator, who contracts with the Sending Party as TPSP.
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 Acquirer.
Merchant Category Code mcc N 4 M:Mandatory Convenience store is represented by "5411".
Merchant Name merchantName ANS 1-25 M:Mandatory "UnionPay International"
Merchant City merchantCity ANS 1-12 M:Mandatory "Shanghai"
Merchant Country Code merchantCountry N 3 M:Mandatory "156"
Retrieval Reference Number retrievalReferenceNumber AN 12 M:Mandatory The Retrieval Reference Number shall be a unique value of the any transactions presented by the acquirer on each settlement day. Format: MMDDhh (first 6 digits of Transmission Date and Time) + System Trace Audit Number (6 numeric digits)
Encrypted Data encData Object M:Mandatory JWE
Primary Account Number pan AN 1-19 M:Mandatory "6211110000000001234" Encrypted with the public key of the Encryption Certificate. The "pan" can be the card number or a token representing the Cardholder account.
Card Sequence Number cardSeqNo N 3 C:Conditional It is a number assigned to a specific IC card when two or more individual cards are associated with the same PAN. It shall be present if the terminal can obtain card sequence number.
PAN Expiry Date panExpiryDate N 4 O:Optional "2203" Expiration date of the account number or token in YYMM format.
Track 1 Data track1 ANS 1-79 C:Conditional Filled with the track 1 data in the card, including field separators, but excluding beginning, ending, and LRC characters. It shall be present if it is a magnetic stripe card transaction and only track 1 data exists on the card.
Track 2 Data track2 ANS 1-37 C:Conditional Filled with the track 2 data on the card, including field separators, and excluding the ending sentinel and LRC characters. It is present if track 2 data exists on the card in card-present transactions.
Track 3 Data track3 ANS 1-104 C:Conditional Filled with the track 3 data on the card, including field separators, and excluding the ending sentinel and LRC characters. It is present if track 3 data exists on the card in card-present transactions.
IC Card Data chipData ANS 1-255 C:Conditional It is present in IC card transactions upon business requirement. This field uses a TLV (tag-length-value) representation. For detailed definition of “chipData”, please refer to Annex B: IC Card Data.
PIN Data pinData B 64 C:Conditional “0000011000010010010100111101111111111110110111001011101010011000” 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 and performed with Base64 encoding.It is present upon the business requirement.
PIN Encryption Algorithm pinEncryptAlg N 1 C:Conditional “7” Filled with the digital encryption algorithm to encrypt the PIN. Valid value: “7”: Triple length 3DES algorithm; It is present if the PIN Data exists.
Terminal Information terminalInfo Object M:Mandatory
Terminal Type terminalType N 2 M:Mandatory “03” Valid Values: “03”: POS; “23”: mPOS; Other values: Reserved
Terminal Identifier terminalId ANS 8 M:Mandatory A unique identification code of each terminal in the network of the acquiring institution.
Terminal Entry Capability terminalEntryCapability N 1 M:Mandatory “6” Valid Values: “0”: Unknown; “2”: Magnetic stripe read capability; “5”: Chip-capable terminal. Contact IC card read capability. Optional to read magnetic stripe card. Cannot read contactless IC card. “6”: Chip-capable terminal. Contactless IC card read capability. Optional to read contact IC card and magnetic stripe card. Other values: Reserved
Terminal Product Code terminalProdCd ANS 1-20 O:Optional It is the device information as defined by terminal manufacturer.
Terminal Application Version terminalAppVersion ANS 8 O:Optional A unique code for each application version. Right padded with spaces if less than 8 bytes.
Terminal GPS terminalGps ANS 1-30 O:Optional Format: +(-) latitude/+(-) longitude. “+” denotes north latitude and east longitude; “-“ denotes south latitude and west longitude. Example:“+37.12/-121.23”, “+37/-121”
SIM Card of the Terminal terminalSimCard ANS 1-20 O:Optional The mobile number used by the terminal. Format: country code + mobile number. Example: “+14168362570”, “+8613701234567”
IP Address of the Terminal terminalIpAddress ANS 1-64 O:Optional The public network IP address of the device.
Card Information Capture Method captureMethod N 2 M:Mandatory "02" Valid Values: “02”: Magnetic stripe read. "05": Integrated circuit card read, card data reliable (contact). "07": qUICS Debit/Credit Integrated Circuit Card read (contactless). Other values: Reserved
Chip Condition Code chipCondCode N 1 M:Mandatory “2” Valid Values: “0”: Not applicable. “1”: Last read was not a chip transaction or was a successful chip transaction. “2”: Last read at terminal was a chip transaction, but the transaction failed, e.g., chip had been used as the transaction channel yet could not read the application. The terminal read the magnetic stripe instead.
Signature-Only Indicator sigOnlyIndicator N 1 M:Mandatory “0” Valid Values: “0”: Non Signature-based Credit Card Network. “1”: Signature-based Credit Card Network
Transaction Initiation Mode trxnInitMode N 1 M:Mandatory “1” Valid Values: “0”: Unknown. “1”: Attended transactions that are initiated on attended terminals. “2”: Unattended transactions, including card-present transaction initiated from the Cardholder-activated terminal (CAT), ATM transaction and card-not-present self-service transaction. “3”: Agent transactions that are initiated by the Merchant on behalf of the Cardholder who is not present, like recurring and MO/TO. “4”: Batch Agent transactions that are initiated by the Merchant in batch on behalf of the Cardholder who is not present, like batch recurring and batch MO/TO. “5”: Deferred online authorization, unattended transactions. “6”: Deferred online authorization, attended transactions
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. The transaction amount in the response message may be not equal to that in the request message due to discount activity, which will be used in settlement.
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. It is present if the tip or convenience fee exists.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message ID msgID AN 37 R:Returned "S00010340001034420171230235959000000" It is used to match a response to its request. The value must uniquely identify any message that the Acquirer initiates on any day. The value in the response must match the value in the request. Components: “S”+ Acquirer IIN +Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits)
Issuer IIN receivePartyIIN AN 8 M:Mandatory The identifier associate to the Issuer.
Retrieval Reference Number retrievalReferenceNumber AN 12 R:Returned The Retrieval Reference Number shall be a unique value of the any transactions presented by the acquirer on each settlement day. Format: MMDDhh (first 6 digits of Transmission Date and Time) + System Trace Audit Number (6 numeric digits)
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. The transaction amount in the response message may be not equal to that in the request message due to discount activity, which will be used in settlement.
Transaction Currency trxCurrency N 3 R:Returned "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.
Authorization Identification Response authCode AN 6 O:Optional “000000” The authorization code for the approved transaction assigned by the Issuer.
Payment Reference Number (PAR) par AN 29 C:Conditional It is present when PAR is available.
Discount Details discountDetails Array O:Optional [{“discountAmt”:”10”,”discountNote”:”Reduction Discount”}] The details of discount. The discount information could be displayed to the cardholder in the terminal interface or the receipt printed to the cardholder.
Discount Amount discountAmt ANS 1-13 O:Optional “20” The amount of discount, which could be displayed to the cardholder in the terminal interface or the receipt printed to the cardholder.
Discount Note discountNote ANS 1-50 O:Optional “Reduction discount” The note of discount, which could be displayed to the cardholder in the terminal interface or the receipt printed to the cardholder.
Original Amount originalAmount ANS 1-13 O:Optional “131.10” The original amount, which could be displayed to the cardholder in the terminal interface or the receipt printed to the cardholder.
Cost Amount costAmount ANS 1-13 O:Optional “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 terminal interface or the receipt printed to the cardholder.
Settlement Date settlementDate N 4 C:Conditional "1230" Format: MMDD. It is present if the payment is approved.
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. It is present if the payment is approved and 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. It is present if the payment is approved and the "cardholderBillingCurrency" has a different value from "trxCurrency"
Cardholder Billing Conversion Rate cardholderBillingConvRate ANS 1-9 C:Conditional "71212345 " It is present if the payment is approved and the "cardholderBillingCurrency" has a different value from "trxCurrency". 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
Conversion Date conversionDate N 4 C:Conditional "1230" Format: MMDD. It is present if either "settlementAmt" or “cardholderBillingAmt”exists
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. Pre-authorization

时序图-preauth.png

1.The Acquirer submits a POS_PREAUTH request message to the UNIONPAY API system.

2.The UNIONPAY API system forwards the payment request to the Issuer and brings back the transaction outcome to the Acquirer in the POS_PREAUTH response message. 

Exceptional flows: 

3.When the Acquirer does not receive the POS_PREAUTH response message within 45 seconds, it can initiate a MSG_RESULT_INQUIRY message, using the Message ID of the POS_PREAUTH to check if the payment is successful.

4.The UNIONPAY API system will return the POS_PREAUTH transaction outcome to the Acquirer.
Steps to Launch
Steps to Launch

Acquirers are required to be UPI member and fill in the application form;

Perform system enhancement according to UPI specifications；

Perform POS terminal enhancement and certification.


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