Unified order

Application scenarios

In addition to the payment code payment scenario, the merchant system first calls the interface to generate the prepayment transaction sheet in the wechat payment service background, returns the correct pre payment transaction session ID, and then generates transaction strings to initiate payment according to different scenarios such as native, jsapi, app, etc.

State machine

The payment status changes as follows:

Interface link

URL address: https://api.mch.weixin.qq.com/pay/unifiedorder

URL address: https://api2.mch.weixin.qq.com/pay/unifiedorder (alternate domain name) See cross city redundancy plan

Do you need a certificate

no

Request parameters

Field name Variable name Required type Example values describe
Public account ID appid yes String(32) wxd678efh567hg6787 The public account ID assigned by wechat payment (the enterprise number Corpid is the appid)
Merchant number mch_ id yes String(32) one billion two hundred and thirty million one hundred and nine Merchant number assigned by wechat payment
Equipment number device_ info no String(32) 013467007045764 User defined parameters, which can be terminal device number (store number or cashier ID), payment in PC web page or public number can be transferred to "Web"
Random string nonce_ str yes String(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS The length of the string should be within 32 bits. recommend Random number generation algorithm
autograph sign yes String(32) C380BEC2BFD727A4B6845133519F3AD6 The signature value calculated by the signature algorithm is shown in Signature generation algorithm
Signature type sign_ type no String(32) MD5 The signature type is MD5 by default. Hmac-sha256 and MD5 are supported.
Product description body yes String(128) Tencent recharge Center - QQ member recharge

A brief description of the product. Please pass this field according to the specification. Please refer to Parameter specification

Commodity details detail no String(6000)   Detailed description of goods. For merchants using single product discount, this field must be uploaded according to the specification. Please refer to "Description of preferential parameters of single product"
Additional data attach no String(127) Shenzhen Branch Additional data is returned in the query API and payment notice as the original, which can be used as a user-defined parameter.
Merchant No. Order No out_ trade_ no yes String(32) twenty trillion and one hundred and fifty billion eight hundred and six million one hundred and twenty-five thousand three hundred and forty-six The internal order number of merchant system is required to be within 32 characters, which can only be numbers and upper and lower case letters_ -|*And it is unique under the same merchant account. See Merchant order number
Price currency fee_ type no String(16) CNY 4217 RMB, please refer to CNY standard list for details Currency type
Bid price amount total_ fee yes Int eighty-eight Total order amount, unit: min, see Payment amount
Terminal IP spbill_ create_ ip yes String(64) 123.12.12.123 Support IP address in IPv4 and IPv6 formats. User's client IP
Transaction start time time_ start no String(14) twenty trillion and ninety-one billion two hundred and twenty-five million ninety-one thousand and ten The order generation time is in the format of yyyymmddhhmmss. For example, 9:10:10 on December 25, 2009 is 20091225091010. For others, see Rules of time
Transaction end time time_ expire no String(14) twenty trillion and ninety-one billion two hundred and twenty-seven million ninety-one thousand and ten

For example, 2009mmy1027, the order will be invalid in the format of 2009mmy1027. When an order is transferred to an order, there must be a payment time_ Id only has a validity period of two hours, so when the re-entry time exceeds 2 hours, you need to re request the single interface to obtain a new pay_ id。 For others, see Rules of time

time_ The value of "expire" can only be transmitted for the first time. It is not allowed to modify it again. The system will report an error if it is modified twice. If the user needs to pay again after the failure of payment, the original order number should be replaced and the order should be placed again.

Suggestion: the shortest failure time interval is more than 1 minute

Order discount mark goods_ tag no String(32) WXG Order discount mark, parameters required when using voucher or discount function. Please refer to Voucher or concession
Notification address notify_ url yes String(256) http://www.weixin.qq.com/wxpay/pay.php The callback address for receiving the notification of wechat payment results asynchronously. The notification URL must be an accessible URL on the Internet and cannot carry parameters.
Transaction type trade_ type yes String(16) JSAPI

Jsapi - jsapi payment

Native - native payment

App - App payment

Please refer to Parameter specification

Commodity ID product_ id no String(32) 12235413214070356458058 trade_ When type = native, this parameter is required. This parameter is the commodity ID contained in the QR code, which is defined by the merchant.
Specified payment method limit_ pay no String(32) no_ credit Upload this parameter no_ Credit -- can restrict the user from paying by credit card
User ID openid no String(128) oUpF8uMuAJO_ M2pxb1Q9zNjWeS6o trade_ When type = jsapi (i.e. jsapi payment), this parameter must be passed. This parameter is the unique ID of wechat user under the corresponding appid of the merchant. How to get openid【 Get openid 】。 Please use the enterprise number【 Enterprise oauth2.0 interface 】Get the userid of the member in the enterprise number, and then call【 Openuserid to enterprise ID 】Make the conversion
E-invoice entry open sign receipt no String(8) Y Y. When y is passed in, the billing entry will appear on the payment success message and payment details page. The function of electronic invoice needs to be opened in wechat payment merchant platform or wechat public platform, and then it can take effect after passing this field
+ Scene information scene_ info no String(256)

{"store_ info" : {
"id": "SZTX001",
"Name": "Tengda restaurant",
"area_ code": "440305",
"Address": Tencent building, 1st Road, Science Park

This field is often used to report the scene information of offline activities. It supports the reporting of actual store information. Merchants can also report relevant information according to their needs. This field is the JSON object data, and the object format is {"store"_ "Store name" {ID "," area name "{ID", "_ Code ":" code "," address ":" address "}}, please click + at the front of the line to expand the field details

Examples are as follows:

<xml>
   <appid>wx2421b1c4370ec43b</appid>
< attach > test
< body > jsapi payment test</body>
   <mch_ id>10000100</mch_ id>
   <detail><![CDATA[{ "goods_ detail":[ { "goods_ id":"iphone6s_ 16G", "wxpay_ goods_ id":"1001", "goods_ name":"iPhone6s 16G", "quantity":1, "price":528800, "goods_ Category ":" 123456 ", " body ":" Apple phone " }, { " goods_ id":"iphone6s_ 32G", "wxpay_ goods_ id":"1002", "goods_ name":"iPhone6s 32G", "quantity":1, "price":608800, "goods_ Category ":" 123789 ", " body ":" Apple phone " } ]] > < / detail >
   <nonce_ str>1add1a30ac87aa2db72f57a2375d8fec</nonce_ str>
   <notify_ url>http://wxpay.wxutil.com/pub_ v2/pay/notify.v2.php</notify_ url>
   <openid>oUpF8uMuAJO_ M2pxb1Q9zNjWeS6o</openid>
   <out_ trade_ no>1415659990</out_ trade_ no>
   <spbill_ create_ ip>14.23.150.211</spbill_ create_ ip>
   <total_ fee>1</total_ fee>
   <trade_ type>JSAPI</trade_ type>
   <sign>0CB01533B8C1EF103065174F50BCA001</sign>
</xml>

Note: the parameter value can be escaped by XML, and CDATA tag is used to indicate that the data is not parsed by XML parser.

Return results

Field name Variable name Required type Sample value describe
Return status code return_ code yes String(16) SUCCESS

SUCCESS/FAIL

This field is a communication ID, not a transaction ID. if the transaction is successful, you need to check the result_ Code

Return information return_ msg yes String(128) OK

When return_ When the code is fail, the returned information is the cause of the error, such as

Signature failed

Parameter format verification error

Return in the following fields_ When the code is success, it will return

Field name Variable name Required type Sample value describe
Public account ID appid yes String(32) wx8888888888888888 Public account ID submitted by calling interface
Merchant number mch_ id yes String(32) one billion nine hundred million one hundred and nine Call the merchant number submitted by the interface
Equipment number device_ info no String(32) 013467007045764 User defined parameter, which can be the terminal device number for payment request, etc
Random string nonce_ str yes String(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS Random string returned by wechat
autograph sign yes String(32) C380BEC2BFD727A4B6845133519F3AD6 For the signature value returned by wechat, please refer to signature algorithm
Business results result_ code yes String(16) SUCCESS SUCCESS/FAIL
error code err_ code no String(32)   When result_ If the code is fail, the error code is returned. Please refer to the error list below for details
Error code description err_ code_ des no String(128)   When result_ If the code is fail, the error description is returned. Please refer to the error list below for details

The following fields are in return_ Code result and_ When the code is success, it will return

Field name Variable name Required type Example values describe
Transaction type trade_ type yes String(16) JSAPI

Jsapi - jsapi payment

Native - native payment

App - App payment

Please refer to Parameter specification

Pre payment transaction session ID prepay_ id yes String(64) wx201410272009395522657a690389285100 The pre payment session ID generated by wechat is used in subsequent interface calls. The value is valid for 2 hours
QR code link code_ url no String(64) weixin://wxpay/bizpayurl/up?pr=NwY5Mz9&groupid=00

trade_ When type = native, the URL is used to generate payment QR code, and then provide it to users for scanning code payment.

Note: Code_ The value of URL is not fixed, so it can be converted into QR code according to the URL format

Examples are as follows:

<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>
   <openid><![CDATA[oUpF8uMuAJO_ M2pxb1Q9zNjWeS6o]]></openid>
   <sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
   <result_ code><![CDATA[SUCCESS]]></result_ code>
   <prepay_ id><![CDATA[wx201411101639507cbf6ffd8b0779950874]]></prepay_ id>
   <trade_ type><![CDATA[JSAPI]]></trade_ type>
</xml>

Error code

name describe reason Solution
INVALID_ REQUEST Parameter error The parameter format is wrong or not uploaded according to the rules When the order is re entered, the parameter value is required to be consistent with the original request. Please confirm the parameter problem
NOAUTH The merchant does not have this interface authority The merchant has not opened this interface permission Please apply for this interface permission
NOTENOUGH Sorry, your credit is running low Insufficient balance of user account The balance of the user account is insufficient. Please recharge or replace the payment card before paying
ORDERPAID Merchant order paid Merchant's order has been paid, no repeat operation is required Merchant's order has been paid, no more operation is required
ORDERCLOSED Order closed The current order is closed and cannot be paid The current order has been closed, please order again
SYSTEMERROR System error System timeout System exception, please call again with the same parameters
APPID_ NOT_ EXIST Appid does not exist Missing appid in parameter Please check whether the appid is correct
MCHID_ NOT_ EXIST Himcd does not exist Missing mchid in parameter Please check if mchid is correct
APPID_ MCHID_ NOT_ MATCH Appid and MCH_ ID mismatch Appid and MCH_ ID mismatch Please confirm appid and MCH_ Does the ID match
LACK_ PARAMS Missing parameter Missing required request parameters Please check whether the parameters are complete
OUT_ TRADE_ NO_ USED Duplicate merchant order number The same transaction cannot be submitted more than once Please check whether the merchant's order number is repeatedly submitted
SIGNERROR Signature error Parameter signature result is incorrect Please check whether the signature algorithm of both parameter and method meets the requirements
XML_ FORMAT_ ERROR XML format error XML format error Please check that the XML parameter format is correct
REQUIRE_ POST_ METHOD Please use the post method The parameter was not passed using post Please check whether the request parameters are submitted through the post method
POST_ DATA_ EMPTY Post data is empty Post data cannot be empty Please check whether post is empty
NOT_ UTF8 Code format error The specified encoding format is not used Please use UTF-8 encoding format