Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Unified Order API

Latest update time:2019.11.20 Release notes


For scenarios other than the Quick Pay method, the Merchant’s backend calls this API to create an advance transaction in the WeChat payment service backend, and initiates the payment process via payment by QR Code. JSAPI, App and other payment methods after the order is submitted successfully.

API intro

Request Url: https://api.mch.weixin.qq.com/pay/unifiedorder

Request Method: POST

Certificate Requirements: No certificate is required.

Applicable Object: Common modeInstitutional mode

Request Parameter

Field Name ID Type Required Description
Official Account ID appid String(32) Yes Specifies an Official Account ID assigned by WeChat
Example:wx8888888888888888
Merchant ID mch_id String(32) Yes Specifies merchant ID assigned by WeChat Payment
Example:1900000109
Sub  Merchant ID sub_mch_id String(32) Yes Specifies Sub merchant ID assigned by WeChat Payment
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example:1900000109
Device ID device_info String(32) No

Specifies the terminal device ID assigned by WeChat Payment. This field is defined by the Merchant.

Note: If the payment is performed based on PC web page or WeChat Web-based page, please submit the field value as WEB.

Example:013467007045764

Random string nonce_str String(32) Yes 32 characters or fewer. For more information, see Random String Algorithm .
Example:5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm .
Example:C380BEC2BFD727A4B6845133519F3AD6
Sign type sign_type String(32) NO Currently HMAC-SHA256 and MD5 are supported, default is MD5. This field is only required when sign_type is HMAC-SHA256.
Example:HMAC-SHA256
Item Description body String(128) Yes Please refer to Requirements for field body
Example: iPad Mini in white with 16G memory
Items Details detail String(6000) Yes Displays detailed item list
Example:{"goods_detail": [{ "wxpay_goods_id ":"1001"}] }
Additional Data attach String(128) No Allow merchants an additional field to be returned in the payment notification after submitting a payment to the Query Order API
Example: Additional description
Vendor Order Number out_trade_no String(32) Yes 32 alphanumeric characters or fewer.
Example:1217752501201407033233368018
Currency Type fee_type String(16) Yes ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type.
Example:USD
Total Amount total_fee int Yes

Specifies the total order amount. The units are expressed in cents and must be an integer. For more information, see Payment Amount
Example:888

Terminal IP spbill_create_ip String(64) Yes Specifies the client IP of the consumer, both IPv4 and IPv6 are supported.
Example:8.8.8.8
Transaction Start Time time_start String(14) No Specifies the transaction creation time in the format yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10 (UTC+08). For more information, see Time Protocol.
Example:20091225091010
Transaction End Time time_expire String(14) No Specifies the transaction end time in the format yyyyMMddHHmmss, such as 20091227091010 for Dec 27, 2009 09:10:10 (UTC+08). For more information, see Time Protocol.
Example:20091227091010
Item Label goods_tag String(32) No Specifies the label of goods, which is a parameter in the coupon feature for businesses. Keep it null if there is no value.
Example: WXG
Notification URL notify_url String(256) Yes

Specifies the callback address for receiving WeChat payment notifications.

Example: http://www.baidu.com/
Transaction Type trade_type String(16) Yes Value: MWEB
Example: MWEB
Limit payment mothod limit_pay String(32) No Vendor can limit the payment mothod: no_credit—Credit card cannot be used
Example: no_credit
Scenarios Information scene_info String(256) No Specify the payment scenarios, such as the store or mall information.
{
“store_id”:””, //Unique ID of store, Optional,
string(32)
“store_name”:””//Store name, Optional,
string(64)
}
Example:
{ "store_id": "SZT10000", "store_name":"Dining Hall of Tencent Mansion" }

Example:


<xml>
   <appid>wxce926ea78004260e</appid>
   <body>An apple</body>
   <device_info>123001</device_info>
   <fee_type>USD</fee_type>
   <mch_id>1900012291</mch_id>
   <nonce_str>f6868b9b16bf4893958afd4a46d73422</nonce_str>
   <notify_url>https://localhost/api/apm/notify/wechat</notify_url>
   <out_trade_no>1678371718207331</out_trade_no>
   <spbill_create_ip>14.23.150.211</spbill_create_ip>
   <sign>FA5B2EA0A6FD392DBE322A54F3902C00</sign>
   <sub_mch_id>11611403</sub_mch_id>
   <total_fee>1</total_fee>
   <trade_type>MWEB</trade_type>
</xml>                
    
{
JAVA示例代码
}
    

Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.

Return Data

Field Name ID Type Required Description
Return Status Code return_code String(16) Yes Set to SUCCESS or FAIL
Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field.
Example:SUCCESS
Return Data return_msg String(128) No If not empty, this is the error description. If not empty, this is the error description
Signature Failure
Parameter format checking error
Example:Signature Failure

If return_code is SUCCESS, return data will also include the following fields:


Field Name ID Type Required Description
Official Account ID appid String(32) Yes The Official Account ID submitted when calling the interface
Example:wx8888888888888888
Merchant ID mch_id String(32) Yes The Merchant ID submitted when calling the interface
Example:1900000109
Sub Official Account ID sub_appid String(32) No The Sub Official Account ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example:wx8888888888888888
Sub  Merchant ID sub_mch_id String(32) Yes The Sub Merchant ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example:1900000109
Device ID device_info String(32) No Specifies the ID of the terminal device with from which the Merchant submitted their order
Example:013467007045764
Random String nonce_str String(32) Yes 32 characters or fewer
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm .
Example:C380BEC2BFD727A4B6845133519F3AD6
Service Result result_code String(16) Yes Set to SUCCESS or FAIL
Example:SUCCESS
Error Code err_code String(32) No Please refer to Error Codes
Example:SYSTEMERROR
Error Code Description err_code_des String(128) No The detailed description of error
Example:System error

If return_code and result_code are SUCCESS, return data will also include the following fields:


Field Name ID Type Required Description
Transaction Type trade_type String(16) Yes Value: MWEB
Example: MWEB

Advance Transaction ID prepay_id String(64) Yes Specifies the advance transaction ID created by WeChat. It is used to call the WeChat Payment API later.
Example: wx201410272009395522657a690389285100
Payment Jump URL mweb_url String(512) Yes Mweb_url is used to call the WeChat payment, which will be loaded when requesting this url.
Example: https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?
prepay_id=wx20161215164202424443
21ca0631331346&package=1405458241

Example:


<xml>
   <return_code><![CDATA[SUCCESS]]></return_code>
   <return_msg><![CDATA[OK]]></return_msg>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <mch_id><![CDATA[10000100]]></mch_id>
   <nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
   <sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
   <result_code><![CDATA[SUCCESS]]></result_code>
   <prepay_id><![CDATA[wx201411101639507cbf6ffd8b0779950874]]></prepay_id>
   <trade_type><![CDATA[MWEB]]></trade_type>
   <mweb_url><![CDATA[https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016121516420242444321ca0631331346&package=1405458241]]></mweb_url>
</xml>

Error Codes

Name Description Reason Solution
INVALID_REQUEST Parameter error Parameter format is wrong or parameter transferring didn’t follow the rules. Please check whether the parameters are transferred right.
NOAUTH Merchant doesn’t have permission to use this API Merchants hasn’t enabled authorization for this API. The Merchant should apply for permission to use this API
NOTENOUGH Insufficient balance The Payer has an insufficient balance in their payment card. Inform the Payer to add funds to their account or or to try another payment card.
ORDERPAID Order is paid Order is already paid and cannot be paid for again. The order has already been paid and no further action is required.
ORDERCLOSED Order is closed The current order is closed and cannot be paid for again. The current order has already been closed. The Payer should be told to create a new order.
SYSTEMERROR System error System has timed out A system exception has occurred. Call the API again using the same parameters.
APPID_NOT_EXIST APPID DOES NOT EXIST Provided APPID in this parameter does not exist. Check whether provided APPID is correct.
MCHID_NOT_EXIST MCHID DOES NOT EXIST Provided MCHID in this parameter does not exist. Check whether provided MCHID is correct.
APPID_MCHID_NOT_MATCH Appid does not match mch_id. Appid does not match mch_id Check whether appid belongs to the associated mch_id
LACK_PARAMS Missing parameter Required parameter is missing. Check whether parameter is provided.
OUT_TRADE_NO_USED Duplicate merchant order number The same transaction can't be submitted repeatedly. Check whether merchant's order number has already been submitted or used previously.
SIGNERROR Signature error Incorrect signature result Check whether signature parameter and method comply with signature algorithm requirements.
XML_FORMAT_ERROR INVALID XML FORMAT INVALID XML FORMAT Check whether XML parameters are in correct format.
REQUIRE_POST_METHOD Use post method Data is not transferred by post . Check whether data is submitted via POST method.
POST_DATA_EMPTY Post data is empty. Post data can’t be empty Check whether post data is empty.
NOT_UTF8 Invalid coding format Specified coding format is not used. Use NOT_UTF8 coding format


Release notes

关闭
V1.0
2019.11.20
1. Unified Order API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global