Order Placement API
Latest update time：2024.03.07 Release notes
The Merchant’s backend calls this API to create an advance transaction in the WeChat payment service backend
1. API intro
Applicable object:Common modeInstitutional mode
Request URL: https://apihk.mch.weixin.qq.com/v3/global/transactions/mweb
Request method: POST
Pathparameter is a path parameter.
Queryparameter needs to be passed in the request URL.
Bodyparameter needs to be passed in the request JSON.
2. Request Parameters
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| Merchant ID | mchid | string[1,32] | Yes | Body Merchant ID assigned by WeChat Pay Note: Only forCommon mode Example: 1900000109 |
| APPID | appid | string[1,32] | Yes | Body APPID corresponding to the mobile app applied by the merchant on the WeChat Open Platform Note: Only forCommon mode Example: wx8888888888888888 |
| Sub-merchant ID | sub_mchid | string[1,32] | Yes | Body Sub-merchant ID assigned by WeChat Pay Note: Only forInstitutional mode Example: 1900000109 |
| Institution's Merchant ID | sp_mchid | string[1,32] | Yes | Body Institution's Merchant ID assigned by WeChat Pay Note: Only forInstitutional mode Example: 1900000100 |
| Organization APPID | sp_appid | string[1,32] | Yes | Body APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform Note: Only forInstitutional mode Example: wx8888888888888888 |
| Sub-merchant APPID | sub_appid | string[1,32] | No | Body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform |
| Product description | description | string[1,128] | Yes | Body Brief description of the product or payment order in the following format: Name of the store brand - Name of the city branch - Name of the actual product. Example: Image Store - Tencent Building in Shenzhen - QQ Doll |
| Merchant data | attach | string[1,127] | No | Body Additional data, which will be returned unchanged in the query API and payment notifications. This field is mainly used for the custom data in the orders of the merchant. Example: Custom data |
| Notification address | notify_url | string[1,256] | Yes | Body The callback address to receive WeChat Pay result notifications asynchronously. The notification URL must be accessible by external networks, and is not allowed to carry any parameters. Use the HTTPS protocol URL. Example: https://www.weixin.qq.com/wxpay/pay.php |
| Merchant order No. | out_trade_no | string[1,32] | Yes | Body The order No. in the merchant system with the length of not more than 32 characters, including letters. If the authorization code changes, a new merchant order No. must be used. For more information, see Merchant Order No. Example: 1217752501201407033233368018 |
| Product tag | goods_tag | string[1,32] | No | Body The product tag, which is a parameter for the voucher or discount feature. For more information, see Vouchers or Discounts. Example: WXG |
| Transaction type | trade_type | string[1,16] | Yes | Body OfficialPayment：JSAPI Native Payment: NATIVE In-APP payment: APP H5 payment: MWEB QuickPay: MICROPAY MiniProgram payment: JSAPI Example: MWEB |
| Payment method | limit_pay | string[1,32] | No | Bodyno_credit - Credit card cannot be used for payment Example: no_credit |
| Start time of a transaction | time_start | string[1,64] | No | Body Order generation time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. Example: 2018-06-08T10:34:56+08:00 |
| End time of a transaction | time_expire | string[1,64] | No | Body Order expiration time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. The order expiration time is specific to the order No. Since the code_url returned by the API is only valid for two hours, it is necessary to request the API again to obtain a new code_url after two hours. It is recommended that the minimum expiration time interval be greater than 1 minute. Example: 2018-06-08T10:34:56+08:00 |
| MCC code | merchant_category_code | string[1,16] | Yes | Body Merchant category codes,see Merchant category codes Example: 1011 |
| Payer | payer | object | No | Body Payer information. For more information. |
| Order amount | amount | object | Yes | Body Information on the order amount. For more information, see the description below. |
| Scenario information | scene_info | object | Yes | Body The scenario information object. For more information, see the description below. |
| Discount feature | detail | object | No | Body Discount feature info. For more information, see the description below. |
Request Eample：
{
"sp_appid": "wx2421b1c4370ec43b",
"sp_mchid": "10000100",
"sub_mchid": "20000100",
"out_trade_no": "20150806125346",
"merchant_category_code": "1011",
"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
"trade_type": "MWEB",
"amount": {
"total": 10000,
"currency" : "HKD"
},
"attach": "Payment test",
"description": "H5 payment test",
"goods_tag": "",
"detail" : {
"cost_price": 10000,
"receipt_id" : "1234",
"goods_detail": [
{
"goods_id":"iphone6s_16G",
"wxpay_goods_id":"1001",
"goods_name":"iPhone6s 16G",
"quantity":1,
"price":528800
}
]
},
"scene_info": {
"payer_client_ip" : "14.23.150.211",
"device_ip" : "59.37.125.32",
"device_id" : "013467007045764",
"operator_id": "P001",
"store_info" : {
"id": "SZTX001"
}
}
}
3. Response Parameters
Response for successful request
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| The payment redirect URL | mweb_url | string[1,512] | Yes | mweb_url is the middle page that calls the WeChat Pay cashier. Call the WeChat client by visiting the URL to complete the payment. The validity period of mweb_url is 5 minutes. Example: https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb? prepay_id=wx2016121516420242444321 ca0631331346&package=1405458241 |
Response for failed request:
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| Returned status code | code | string[1,32] | Yes | Error code. See the error code list for the enumerated values. |
| Returned information | message | string[1,256] | Yes | Returned message. It indicates the reason for the error if not empty. |
| Detailed error description | detail | object | No | It is returned when code is PARAM_ERROR. Details will be described below. |
Response Example:
{
"mweb_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016121516420242444321ca0631331346&package=1405458241"
}
4. Error Codes
| Error Message | Description | Solution |
|---|---|---|
| NO_AUTH | The merchant does not have access to the API. | Let the merchant to apply for access to the API. |
| NOT_ENOUGH | Insufficient balance | The user's account balance is insufficient. Top up or use another payment card. |
| ORDER_PAID | Merchant order paid. | Merchant order paid. Other operation not needed. |
| ORDER_CLOSED | Order closed | Order closed. Place a new order. |
| SYSTEM_ERROR | System error | System exception. Call again with the same parameters. |
| APPID_NOT_EXIST | APPID does not exist. | Check whether APPID is correct. |
| MCHID_NOT_EXIST | MCHID does not exist. | Check whether MCHID is correct. |
| APPID_MCHID_NOT_MATCH | appid and mchid do not match. | Check whether appid and mchid match. |
| LACK_PARAMS | Missing parameters | Check if the parameters are complete. |
| OUT_TRADE_NO_USED | Duplicate merchant order number | Check whether the merchant order number is submitted repeatedly. |
| SIGN_ERROR | Signature error | Check if signature parameters and methods meet the algorithm requirements. |
| REQUIRE_POST_METHOD | Use post method. | Check whether the request parameter is submitted via post method. |
| POST_DATA_EMPTY | post is empty. | Check whether post is empty. |
| NOT_UTF8 | Incorrect encoding format | Use UTF-8 encoding format. |
Page Navigation
