Open API >Online Payments >Merchant-Hosted
Merchant-Hosted
Online Payments 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

MH SP流程图.png

1. Cardholder chooses product on a merchant website;

2. The merchant initiates a request message to the acquirer system;

3. The acquirer transfers the transaction to UnionPay Omnichannel Platform (UPOP);

4. Cardholder checks individual's identity on UPOP;

5. UPOP transfers the transaction to UnionPay core processing system;

6. UnionPay core processing system converts FX rate and transfers the transaction to the issuer;

7. The issuer authorizes transaction and the response message goes back to the merchant website over the same route.


API Reference
API Reference
  • 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:Mandatory 5.1.0: Fixed value
Encoding method encoding ANS 1-20 M:Mandatory UTF-8: Default value
Certificate ID certId N 1-128 M:Mandatory The serial number of private key certificate for signature, which can be obtained through SDK provided by UPI.
Signature signature ANS 1-1024 M:Mandatory Fill in message hash signature
Signature method signMethod N 1-12 M:Mandatory 01: RSA
Transaction type txnType N 2 M:Mandatory 77: SMS-sending
Transaction sub-type txnSubType N 2 M:Mandatory Used to specify SMS type:05: Easy enrollment
Product type bizType N 6 M:Mandatory 000301: Merchant-hosted
Access type accessType N 1 M:Mandatory 0: Merchant direct access.1: Acquirer access
Channel type channelType N 2 M:Mandatory 07: Internet.08: Mobile
Acquiring Institution Identification Number acqInsCode AN 8-11 C:Conditional Applied if access type is acquirer access
Merchant ID merId AN 15 M:Mandatory The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant type merCatCode N 4 C:Conditional Fill MCC code. Applied if access type is acquirer access.
Merchant name merName ANS 1-40 C:Conditional Applied if access type is acquirer access
Merchant abbreviation merAbbr ANS 1-8 C:Conditional Applied if access type is acquirer access
Merchant order number orderId AN 8-40 M:Mandatory Must be consistent with follow-up enrollment transaction order number
Order time txnTime N M:Mandatory Must be consistent with follow-up enrollment transaction order time. Format: YYYYMMDDhhmmss
Primary Account Number (PAN) accNo AN 1-1024 M:Mandatory Card number.Must be encrypted by using encryption public key and perform Base64 encoding before submission.
Cardholder verification information customerInfo ANS 1-1024 M:Mandatory 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:Conditional 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:Returned
Signature signature ANS 1-1024 M:Mandatory
Encoding method encoding ANS 1-20 R:Returned
Signature method signMethod N 2 M:Mandatory
Transaction type txnType N 2 R:Returned
Transaction sub-type txnSubType N 2 R:Returned
Product type bizType N 6 R:Returned
Access type accessType N 1 R:Returned
Acquiring Institution Identification Number acqInsCode AN 8-11 R:Returned
Merchant ID merId AN 15 R:Returned
Merchant order number orderId AN 8-40 R:Returned
Order time txnTime N R:Returned Format: YYYYMMDDhhmmss
Requestor reserved field reqReserved ANS 1-1024 R:Returned
Reserved field reserved ANS 1-2048 O:Optional
Response code respCode AN 2 M:Mandatory
Response information respMsg ANS 1-256 M:Mandatory Fill in detailed response information
Public key certificate for Signature signPubKeyCert AN 2048 C:Conditional Return UnionPay public key certificate for signature when RSA is used as signature method
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:
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
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.