Open API >Payment >Merchant-Hosted
Merchant-Hosted
Payment Developer Merchant Acquirer Internet Payment
Merchant-Hosted solution is designed by UnionPay to offer a convenient online payment solution for debit and credit cards without entering PIN. In merchant-hosted solution, cardholders finish enrollment and payment processes at merchant/acquirer end without redirection in the entire payment flow.
API Introduction
API Introduction
Key Features

A frictionless model;

Enrollment and payment steps are finished on the merchant/acquirer page without redirection;

One-click payment for enrolled card;

Debit/Credit card do not need PIN to finish payment;

No SMS verification during the payment;

First time authentication is required to help merchant reduce risk;

UPOP server sends SMS to cardholder mobile devices to identify the cardholder identification;

UPOP server verifies SMS code and forward the mobile number to issuer.


Who Use it?
Merchant, Acquirer and Developer
Where to Use it?
This API is available globally except for mainland China.
Flow Chart
Flow Chart

Secure,MH, EP流程图.png


UPOP: UnionPay Omnichannel Platform, a front system of UPI switch and clearing system that handle transactions of online payment, mobile payment etc

API Document
API Document
  • SMS-sending transaction
  • Enrollment transaction
  • encryption public key certificate update inquiry transaction
  • Transaction state inquiry transaction
  • Purchase transaction
  • Purchase cancellation transaction
  • Refund transaction
  • Pre-authorization transaction
  • Pre-authorization Cancellation transaction
  • Pre-authorization Completion transaction
  • Pre-authorization Completion Cancellation transaction
Interface description
SMS-sending transaction
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Version number version NS 5 M-Must 5.1.0: Fixed value
Encoding method encoding ANS 1-20 M-Must UTF-8: Default value
Certificate ID certId N 1-128 M-Must The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature signature ANS 1-1024 M-Must Fill in message hash signature
Signature method signMethod N 1-12 M-Must 01: RSA
Transaction type txnType N 2 M-Must 77: SMS-sending
Transaction sub-type txnSubType N 2 M-Must Used to specify SMS type:05: Easy enrollment
Product type bizType N 6 M-Must 000301: Merchant-hosted
Access type accessType N 1 M-Must 0: Merchant direct access.1: Acquirer access
Channel type channelType N 2 M-Must 07: Internet.08: Mobile
Acquiring Institution Identification Number acqInsCode AN 8-11 C-Condition Applied if access type is acquirer access
Merchant ID merId AN 15 M-Must The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type merCatCode N 4 C-Condition Fill MCC code. Applied if access type is acquirer access.
Merchant name merName ANS 1-40 C-Condition Applied if access type is acquirer access
Merchant abbreviation merAbbr ANS 1-8 C-Condition Applied if access type is acquirer access
Merchant order number orderId AN 8-40 M-Must Must be consistent with follow-up enrollment transaction order number
Order time txnTime N M-Must Must be consistent with follow-up enrollment transaction order time. Format: YYYYMMDDhhmmss
Primary Account Number (PAN) accNo AN 1-1024 M-Must Card number.Must be encrypted by using encryption public key and perform Base64 encoding before submission.
Cardholder verification information customerInfo ANS 1-1024 M-Must Merchant-hosted (Non-authenticated):Mobile phone number is mandatory.For usage details, please refer to section 4.5.3 for the usage description of customerInfo field.
Requestor reserved field reqReserved ANS 1-1024 O-Optional Merchant self-defined reserved field, it will be returned without change in the transaction response.
Reserved field reserved ANS 1-2048 O-Optional Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.
Encryption certificate ID encryptCertId N 1-128 C-Condition The serial number of public key certificate for encryption.Applied if sensitive information (CVN2, expiration date) or PAN, mobile number is encrypted.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Version number version NS 5 R-Return
Signature signature ANS 1-1024 M-Must
Encoding method encoding ANS 1-20 R-Return
Signature method signMethod N 2 M-Must
Transaction type txnType N 2 R-Return
Transaction sub-type txnSubType N 2 R-Return
Product type bizType N 6 R-Return
Access type accessType N 1 R-Return
Acquiring Institution Identification Number acqInsCode AN 8-11 R-Return
Merchant ID merId AN 15 R-Return
Merchant order number orderId AN 8-40 R-Return
Order time txnTime N R-Return Format: YYYYMMDDhhmmss
Requestor reserved field reqReserved ANS 1-1024 R-Return
Reserved field reserved ANS 1-2048 O-Optional
Response code respCode AN 2 M-Must
Response information respMsg ANS 1-256 M-Must Fill in detailed response information
Public key certificate for Signature signPubKeyCert AN 2048 C-Condition Return UnionPay public key certificate for signature when RSA is used as signature method
Response Code Reference
Response Code Reference
Response code Description
00 Success
01 Transaction failed. For details please inquire overseas service hotline .
02 System is not started or temporarily down, please try again later
03 Transaction communication time out, please initiate inquiry transaction
05 Transaction has been accepted, please inquire about transaction result shortly
06 System is busy, please retry it later.
10 Message format error
11 Verify signature error
12 Repeat transaction
13 Message transaction key element missing
30 Transaction failed, please try using other UnionPay card for payment or contact overseas service hotline
31 Merchant state incorrect. The payment is not completed within the order timeout.
32 No such transaction right
33 Transaction amount exceeds limit
34 Could not find this transaction
35 Original transaction does not exist or state is incorrect
36 Does not match original transaction information
37 Max number of inquiries exceeded or too frequent operations
38 UnionPay risk constraint
39 Transaction is not within the acceptance time range
42 Balance deduction successful but transaction exceeded payment time limit
43 Business not allowed, please contact overseas service hotline for help.
44 Wrong number entered or business not opened, please contact overseas service hotline for help.
45 The original transaction has been refunded or cancelled successfully.
60 Transaction failure, for details, please inquire with your issuer
61 Card number entered is invalid, please double check and enter
62 Transaction failed, issuer does not support this merchant, please change to another bank card
63 Card state is incorrect
64 Card balance is insufficient
65 Error with PIN, expiration date, or CVN2 entered, transaction failure
66 Cardholder identity information or mobile number entered are incorrect, verification failure
67 Limit on number of PIN entry attempts exceeded
68 Your bank card currently does not support this business, please inquire with your bank or overseas service hotline for help
69 Time limit on entry exceeded, transaction failure
70 Transaction has been redirected, waiting for cardholder input
71 Dynamic password or SMS verification code validation failure
72 You have not signed up for UnionPay card-not-present payment service at the bank counter or on your personal online bank, please go to a bank counter or access your online banking to activate it or contact overseas service hotline for help.
73 Payment card has exceeded expiration date
76 Requires encryption verification for activation
77 Bank card has not been activated for authenticated payment
78 Issuer transaction rights limited, for details please contact your issuer
79 The bank card is valid, but issuer does not support SMS verification
80 Transaction failed and the token has expired
81 Monthly accumulated transaction counter (amount) exceeded
82 PIN needs to be verified
84 PIN is required but not submitted
85 Transaction failed, the marketing rules are not met
86 QRC status error
88 QRC not found
89 No Token found, invalid TR status or invalid Token status
98 File does not exist
99 General error
Steps to Launch
Steps to Launch

Please provide the following information to developer@unionpayintl.com , in order for a UnionPay International representative to assist you with your business launch.

 

1.      Company Name

2.      Contact Person's Name

3.      Phone

4.      Business Scope

5.      Regions and Countries

6.      UnionPay Product

7.      Monthly Volumn of Online Business Transaction(USD)

FAQ and Documentation
FAQ and Documentation
Documents:
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.