Open API >Payment >UPI Cross-border B2B Platform
UPI Cross-border B2B Platform
Payment Developer Merchant Acquirer Internet Payment
UPI Cross-Border B2B Payment & Service Platform offers comprehensive online payment service for import and export enterprises including global e-commerce, international and local trading enterprises.
API Introduction
API Introduction
What is it?

UnionPay Cross-Border B2B Payment & Service Platform offers comprehensive online payment service for import and export enterprises including global e-commerce, international and local trading enterprises. The platform takes advantage of API mode and Portal mode to provide safe, convenient, transparent and efficient of cross-border B2B payment solutions, and promotes trade between China and countries or regions around the world.

Key Features

Safety: UnionPay digital payment and receiving solution

Convenience: Easy to pay at anytime and anywhere to reduce labor and time costs

Transparency: Real-time payment notification and status tracking

Efficiency: Funds arrive in time; Online corporate management tools to enhance productivity 


When to Use it?

Online trading scenarios including online marketplace, e-invoice platform and other online platforms, and traditional import and export enterprises and other scenarios

Who Use it?
Online marketplaces, e-invoice platforms and other online platforms, traditional import and export enterprises, as well as acquirers providing online B2B payment service
Where to Use it?
This API is available globally.
Flow Chart
Flow Chart

B2B 业务流程图1.png

B2B 业务流程图2.png

API Document
API Document
  • Purchase
  • Purchase Cancellation
  • Refund
  • Inquiry
Interface description
Merchants with access can initiate an order to UnionPay cross-border B2B payment platform via this interface to make their payments. Depending on transaction subtypes, there are two order payments: Direct and E-Invoice ones. The following are related with direct payment mode, unless otherwise noted.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Version No version NS 5 M-Must 1.0.0 Fixed value:1.0.0
Encoding Method encoding ANS 1-20 M-Must UTF-8 Fixed value:UTF-8
Signature signature ANS 1-1024 M-Must Message summary signature is required
Signature Method signMethod N 1-12 M-Must 01 01:RSA
Transaction Type txnType N 2 M-Must 01 Value: 01
Transaction Subtype txnSubType N 2 M-Must Value: 01 - Direct Payment
Channel Type channelType N 2 M-Must Channel type: 07 – Internet, 08 - Mobile
Access Type accessType N 1 M-Must 0: Direct Access for General Merchants; 1:quirer Access; 2:Platform Merchant Access
Foreground Notification Address frontUrl ANS 1-256 C-Condition Don’t need to fill in when txnSubType is 02; As for 01,it will return results to merchants interface if the frontUrl is uploaded.
Background Notification Address backUrl ANS 1-256 M-Must Available for returning query results to merchants through the background. The notification about transaction results from the background are sent to merchant if submitted.
Acquirer Institution Code acqInsCode AN 8-11 M-Must
Merchant Category merCatCode N 4 M-Must
Merchant Code merId AN 15 M-Must
Secondary Merchant Code subMerId AN 5-15 C-Condition Needs to be submitted if Merchant Type is Platform Merchant Access
Secondary Merchant Name subMerName ANS 1-40 C-Condition Needs to be submitted if Merchant Type is Platform Merchant Access
Secondary Merchant Abbr. subMerAbbr ANS 1-8 C-Condition Needs to be submitted if Merchant Type is Platform Merchant Access
Merchant Order No. orderId AN 8-32 M-Must Generated on the merchant side
Commodity Name orderName ANS 1-64 O-Optional
Commodity Type orderType N 4 O-Optional
Commodity Quantity orderNum N 1-10 O-Optional
Commodity Description orderDesc ANS 1-256 O-Optional
Order Sent On txnTime N 14 M-Must The time point when merchants send their transactions, in the forms of YYYYMMDDhhmmss
Payment Timeout Period payTimeout N 14 O-Optional The time point after which this transaction is considered as failed since its payment is overdue, in the forms of YYYYMMDDhhmmss
Order Amount txnAmt N 1-12 M-Must In cents
Order Currency currencyCode AN 3 M-Must 156 Default of 156
Risk Information Field riskRateInfo ANS 1-2048 O-Optional Submitted by merchants who require risk control according to their specific needs, in the following formats: {variable name 1=value& variable name 2= value & variable name 3= value }
Jump Address Available for the Failed Foreground Transactions frontFailUrl ANS 1-256 C-Condition Don’t need to fill in when txnSubType is 02; As for 01, if the fronFailtUrl is uploaded, the page will jump to his/her URL when the payment is failed (just jump occurred, no transaction information transferred)
Reserved Field for Requestor reqReserved ANS 1-1024 O-Optional Reserved field customized by merchants, will be returned as it is when the response to the transaction is occurred
Reserved Field reserved ANS 1-2048 O-Optional Format: BASE64 (variable name 1=value& variable name 2= value& variable name 3=value)
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Version No version NS 5 R-Return 1.0.0 Fixed value
Encoding Method encoding ANS 1-20 R-Return UTF-8 Fixed value:UTF-8
Signature signature ANS 1-1024 M-Must Message summary signature is required
Signature Method signMethod N 1-12 M-Must 01 Value: 01 (Meaning RSA is enabled)
Transaction Type txnType N 2 R-Return
Transaction Subtype txnSubType N 2 R-Return
Channel Type channelType N 2 R-Return Channel type: 07 – Internet; 08 - Mobile
Access Type accessType N 1 R-Return 0: Direct Access for General Merchants; 1: Acquirer Access; 2: Platform Merchant Access
Acquirer Institution Code acqInsCode AN 8-11 R-Return
Merchant Code merId AN 15 R-Return
Merchant Order No. orderId AN 8-32 R-Return
Order Sent On txnTime N 14 R-Return Format: YYYYMMDDhhmmss
Order Amount txnAmt N 1-12 R-Return
Order Currency currencyCode AN 3 R-Return 156 Default of 156
Reserved Field for Requestor 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 Specific response information is expected
Payment URL payUrl ANS 1-512 C-Condition Payment URL will be returned only if the Response Code is 00;
Asynchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Version No version NS 5 R-Return 1.0.0 Fixed value
Encoding Method encoding ANS 1-20 R-Return UTF-8
Signature signature ANS 1-1024 M-Must Message summary signature is required
Signature Method signMethod N 1-12 M-Must 01 Value: 01 (Meaning RSA is enabled)
Transaction Type txnType N 2 R-Return
Transaction Subtype txnSubType N 2 R-Return
Channel Type channelType N 2 R-Return Channel type:07 - Internet; 08 - Mobile
Access Type accessType N 1 R-Return 0: Direct Access for General Merchants; 1: Acquirer Access; 2: Platform Merchant Access
Acquirer Institution Code acqInsCode AN 8-11 R-Return
Merchant Code merId AN 15 R-Return
Merchant Order No. orderId AN 8-32 R-Return
Order Sent On txnTime N 14 R-Return Format:YYYYMMDDhhmmss
Order Amount txnAmt N 1-12 R-Return
Order Currency currencyCode AN 3 R-Return 156 Default of 156
Reserved Field for Requestor 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 Specific response information is expected
Settlement Amount settleAmt N 1-12 M-Must
Settlement Currency settleCurrencyCode AN 3 M-Must
Settlement Date settleDate N 4 M-Must Format: MMDD
Exchange Date exchangeDate N 4 O-Optional Format: MMDD
Transaction Transferred On traceTime N 14 M-Must Format:YYYYMMDDhhmmss
System Trace No. traceNo N 6 M-Must
Transaction ID transId AN 8-32 M-Must
Sample code
Request code
Other
{txnType=01,payTimeout=20180811171438,frontUrl=http://www.unionpayintl.com/,currencyCode=344,channelType=07,orderType=00,orderDesc=描述描述,frontFailUrl=http://cn.unionpay.com/,orderName=测试商品,merId=005157806020001,orderNum=1,acqInsCode=00510578,txnSubType=01,txnAmt=665000,version=1.0.0,signMethod=01,backUrl=http://172.19.52.40:9081/epsp-sample/backAsyNotice.do,encoding=UTF-8,reqReserved=test,merCatCode=0602,orderId=20180810171438,signature=bcXG+BMFkQ1fGcF5OP8rs6YXp2lUs6VBrR4qtrtlXqVLz0X9wzpNJCyTxXMz63vf9x2GRoKbn/Pna/USjXSBFeGHyeQrI+H1ZCVJ3A9QYziV+glHOr7xtkIbUipc9k4odnlY4XxHcweLfhQXCmIbfaTqAVUx7gaftg0Iw5sNLc1+27JAp2NU2VYgXGBtJj1wSSZMhCGTqTkF1wS2H3HiGRPscgmleHRjhbheEcf9N42/uY4EyEbEGDLll2S8IY2r02ef4t0nkfVJJU8AuvAW8RJeQNLN4Pp9AGFdV8O7/S3+Hk4Sc1R0fPBqPb6jbBl3/foPCoCXCvf3PnXpSu9IYg==,txnTime=20180810171438,accessType=0,}


Response code
Other
[accessType=0&acqInsCode=00510578&channelType=07&currencyCode=344&encoding=UTF-8&merId=005157806020001&orderId=20180810171438&reqReserved=test&respCode=00&respMsg=Success!&settleAmt=665000&settleCurrencyCode=344&settleDate=0810&signMethod=01&signature=WPqb1ykHNr0ezBySxWIp+FBQn6CmuVJm/XA2VhKNNWyrzYp/UX3TNqB5/CnFvhoZwDexXy8rkcpKBj9tfI21/Wu4DYD4X+q1uEhsCTmZDe1pCfz+bv5q6BpyRqxggjdB37OLNEz8T0+xYJ0Ge9THflF5fBBK8lG+k1hMg1rGG4lEzIoTHdDPWGaFjZvZOxcdVab5NGuUwD8HpUcmO/nBafPE3hngVK9mK+d54d1BeerONGmpD+mYHqWp1vMg6Yj9KfVlhal7LRrmWTQSRswTmjqQJO1j7ZaNZnAzcYxuXHXlWW4GUULkxdlBddVc6iEEXcpYZgrEBklBsvKOPCWcpA==&transId=2018081000005113&txnAmt=665000&txnSubType=01&txnTime=20180810171438&txnType=01&version=1.0.0]


Response Code Reference
Response Code Reference
Response code Description
00 Succeed
01 System error
05 Accepted, please inquire transaction results later
08 Illegal merchant information
09 Illegal parameter format
10 Wrong message format
11 Wrong verification signature
12 Duplicate transaction
32 No privilege for this transaction
33 Transaction amount exceeds the limit
34 Not found this transaction
36 Not match with original transaction information
39 Beyond the scope of acceptance time for this transaction
61 Invalid card number entered, please confirm and enter it again
65 Transaction failed due to wrong password, validity or CVN2 entered
66 Transaction failed due to incorrect cardholder’s identity information or phone number entered
90 Illegal currency information
Steps to Launch
Steps to Launch

B2B 业务开展流程1.png

B2B 业务开展流程2.png

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