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 Acquirer
Card Not Present Payment for Acquirer
Online Payments Acquirer Internet Payment
Card Not Present Payment assists Acquirers to implement UPI E-Commerce products via JSON message, including 3-D Secure, SecurePlus and ExpressPay.
Sandbox Testing
API Introduction
API Introduction
What is it?

Card Not Present Payment assists Acquirers to implement UPI E-Commerce products via JSON message, including 3-D Secure, SecurePlus and ExpressPay.

This set of APIs allow acquirers to connect to UPI system with JSON message instead of traditional message in ISO 8385 format.


Key Features

Using Json Message Format, Card Not Present Payment provides standardized Intefaces to developers, making it easy and convenient to access.  

When to Use it?

Online E-Commerce Payment

Who Use it?
Acquirers, Payment Service Providers, Gateways
Where to Use it?
This API is available globally except for China Mainland.
Things to Know

Card Not Present Payment shall be used combining other UnionPay products, including 3DS 2.0, SecurePlus, ExpressPay.

Flow Chart
Flow Chart

Card Not Present Payment Process differs when combining with different products.

When combining with 3DS or SecurePlus, process would be authentication flow followed by authorization flow, i.e. step 1-10

When combining with ExpressPay, process would be authorization flow only, i.e. step 5-10

无卡支付流程图.png

Authentication Flow:

1. Merchant send authentication request(3DS or SecurePlus) to UPI

2. UPI forward request to issuer

3. Issuer return authentication request to UPI

4. UPI return authentication to merchant


Authorization Flow:

5. Merchant initiate transaction to acquirer host

6. Acquirer host send request to UPI by Card Not Present Payment API

7. UPI send request to Issuer

8.9.10 Issuer return response to each party
API Reference
API Reference
  • PURCHASE
  • PREAUTH
  • PREAUTH_COMPLETION
  • VOID
  • REFUND
  • MSG_RESULT_INQUIRY
Interface description
PURCHASE is used for purchase transaction that goods or services are delivered to consumers immediately
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.
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 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.
PAN Expiry Date panExpiryDate N 4 C:Conditional "2203" Encrypted with the public key of the Encryption Certificate. Expiration date of the account number or token in YYMM format. Required when ECI value is 07,10. Not required when ECI value is 05,06,09. Format: YYMM
CNP Check Value cvn2 N 3 O:Optional “123” Encrypted with the public key of the Encryption Certificate
Card Information Capture Method captureMethod N 2 M:Mandatory “01” Valid Values: “01”: MANUAL; “10”: STORED_CREDENTIALS; Reserved Values: “07”: NFC; “05”: CONTACT; “02”: MAGSTRIPE; “00”: UNKNOWN
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,"." shall be used to separate decimals from integer value, and "." may be present even if there are no decimals. 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. Present if the Tip or Convenience Fee exists
Coupon Information couponInfo ANS 1-30 O:Optional
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.
Secondary Merchant ID subMerID AN 5-15 C:Conditional Applied if access type is platform merchant access
Merchant order number orderID AN 8-40 M:Mandatory Generated by Merchant, and it should be unique at merchant side.
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"
Secondary Merchant Name subMerName ANS 1-40 C:Conditional Applied if access type is platform merchant access
Merchant City merchantCity ANS 1-12 M:Mandatory "Shanghai"
Ecommerce Data eComData Object M:Mandatory e-Commerce transaction specific data
Terminal Type terminalType N 2 M:Mandatory “08” Valid Values: “07”: PC; “08”: MOBILE; Reserved Values: “00”: UNKNOWN
Electronic Commerce Indicator eci N 2 C:Conditional “05” Valid Values: “05” – 3DS Authenticated transaction; “06” – 3DS Attempt transaction; “07” – 3DS non-authenticated transaction; “09” – Non-3DS Authenticated transaction, which applies to SecurePlus; “10” – Non-authenticated transaction, which applies to ExpressPay.
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
Verification Code vCode ANS 20 C:Conditional Present if ECI value of 09. Format: YYYYMMDDHHMMSS+6 random digits
Risk Information riskInfo Object O:Optional
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.
Application User ID appUserID ANS 1-64 O:Optional An alias for the application user ID
User Enrollment Date usrEnrolDate N 6 O:Optional "161230" The date when the cardholder registers in the wallet. Format: YYMMDD
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device
Reserved Mobile Number reservedMobileNo ANS 1-25 O:Optional “86-13900000000” The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number. If the country code is not present, UPI API will consider it as a Chinese mobile number.
Device Score deviceScore N 1 O:Optional “5” Valid Values: “1” to “5”. “5” indicates the device is very reliable, and “1” indicates the device is less reliable.
Synchronous Response parameters
Filed 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.
Encrypted Data encData Object O:Optional 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.
PAN Last 4 Digit panLast4 N 4 O:Optional “1234” The last 4 digits of PAN. Returned to acquirer based on configuration.
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, "." shall be used to separate the decimals from the integer value, and "." may be present even if there are no decimals. 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.
Discount Details discountDetails Array O:Optional [{“discountAmt”:”20”,”discountNote”:”Uplan 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 “Uplan 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.
Retrieval Reference Number retrievalReferenceNumber AN 12 C:Conditional Populated by UnionPay if the payment is approved.
Settlement Date settlementDate N 4 C:Conditional "1230" 　Populated by UnionPay if the payment is approved.　Format: MMDD
Settlement Currency settlementCurrency N 3 C:Conditional “840” A 3-digit numeric value, as defined by [ISO 4217], that indicates acquirer’s settlement currency. Populated by UnionPay if the payment is approved and 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.　Populated by UnionPay if the payment is approved and the "settlementCurrency" has a different value from "trxCurrency"
Settlement Conversion Rate settlementConvRate ANS 1-9 C:Conditional "0.15000" Populated by UnionPay if the payment is approved and 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. Populated by UnionPay 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, "." shall be used to separate the decimals from the integer value, and "." may be present even if there are no decimals. Populated by UnionPay if the payment is approved and the "cardholderBillingCurrency" has a different value from "trxCurrency"
Cardholder Billing Conversion Rate cardholderBillingConvRate ANS 1-9 C:Conditional "0.15000" Populated by UnionPay if the payment is approved and the "cardholderBillingCurrency" has a different value from "trxCurrency"
Conversion Date conversionDate N 4 C:Conditional "1230" Populated by UnionPay if either "settlementAmt" or “cardholderBillingAmt”exists, Format: MMDD
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.
Steps to Launch
Steps to Launch

Developers should either perform the role of Acquirers or system developer to apply for business launch.


Please submit order to contact us.
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2023. All rights reserved