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.
Request Url: https://api.mch.weixin.qq.com/pay/unifiedorder
Request Method: POST
Certificate Requirements: No certificate is required.
Applicable Object: Common modeInstitutional mode
| 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 Official Account ID | sub_appid | String(32) | No | Specifies an Sub Official Account ID assigned by WeChat. Required for In-App payment. 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 | 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 | Short description of item(s) to be purchased for the Payer. Example: iPad Mini in white with 16G memory |
| Version ID | version | String(32) | Yes | Fixed value: 1.0 Example：1.0 |
| Items Details | detail | String(6000) | Yes | Detailed mcc code described in JSON format. Please use CDATA tag to protect the JSON string when transferring data. goods_detail └ wxpay_goods_id String Required 32 Note: MCC code is now required when calling payment APIs. Please refer to for the MCC code list. And please refer to the samples of how to transfer the mcc code. Example：{"goods_detail":[{ "wxpay_goods_id ":"0742"}]} |
| Additional Data | attach | String(128) | No | An additional field to be returned in the payment notification, return message of Query Order API after submitting a payment request and return message of Download Reconciliation File API when the payment status is SUCCESS or REFUND. |
| Merchant Order Number | out_trade_no | String(32) | Yes | 32 alphanumeric characters or less. For more information, see Merchant's Order Number. 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 |
| Terminal IP | spbill_create_ip | String(64) | No | Specifies the machine IP that calls WeChat Payment API. |
| 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. 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 | Set to JSAPI, NATIVE, or APP. Example: JSAPI |
| Product ID | product_id | String(32) | No | This ID contains the product ID as set by the Merchant. Example: 12235413214070356458058 |
| User Tag | openid | String(128) | No | This field is only required when trade_type is JSAPI. It is the only user identification under the current appid. About how to get openid, please refer to get openid api. Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| Sub User Tag | sub_openid | String(128) | No | This field is only required when trade_type is JSAPI. It is the only user identification under the current appid. Choose one of openid or sub_openid to submit, if sub_openid is chosen, sub_appid also need to be submitted. Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat PayAbout how to get sub_openid, please refer to get openid api. Note: Only for Institutional mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 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" } |
<xml>
<appid>wx2421b1c4370ec43b</appid>
<body>An apple </body>
<device_info>123001</device_info>
<fee_type>EUR</fee_type>
<mch_id>10000100</mch_id>
<nonce_str>f6868b9b16bf4893958afd4a46d73422</nonce_str>
<notify_url>https://localhost/api/apm/notify/wechat</notify_url>
<out_trade_no>1678371718207330</out_trade_no>
<sign>9EFAE9F4023ECFA091E55B92BE59F9B6</sign>
<sub_mch_id>375907253</sub_mch_id>
<total_fee>1</total_fee>
<trade_type>APP</trade_type>
</xml>
Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.
| 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 | The transaction type submitted. The value could be JSAPI, NATIVE, or APP. |
| 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 |
| QR Code URL | code_url | String(64) | No | This field is returned when trade_type is NATIVE. This parameter should be used to create a QR Code that is displayed to the Payer later. Only for QR Code Payment Example: URl: weixin://wxpay/s/An4baqw |
<xml>
<return_code>![CDATA[SUCCESS]]</return_code>
<return_msg>![CDATA[OK]] </return_msg>
<result_code>![CDATA[SUCCESS]]</result_code>
<mch_id>![CDATA[10000100]]</mch_id>
<appid>![CDATA[wx2421b1c4370ec43b]]</appid>
<sub_mch_id>![CDATA[375907253]]</sub_mch_id>
<device_info>![CDATA[123001]]</device_info>
<nonce_str>![CDATA[oau45q3ZBIghSWMq]]</nonce_str>
<sign>![CDATA[A097F9242DF04CD4467D814987538248]]</sign>
<prepay_id>![CDATA[wx032345531721563d76748ad2f15b480000]]</prepay_id>
<trade_type>![CDATA[NATIVE]]</trade_type>
<code_url>![CDATA[weixin://wxpay/bizpayurl?pr=IjIU6hZzz]]</code_url>
</xml>
| 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 |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证