Order Placement

Update Time：2025.03.21

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.

1. API intro

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/transactions/mweb

Request method: POST

Path parameter is a path parameter.

Query parameter needs to be passed in the request URL.

Body parameter 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 for Common 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 for Common mode
Example: wx8888888888888888

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Body Sub-merchant ID assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109

Institution's Merchant ID

sp_mchid

string[1,32]

Yes

Body Institution's Merchant ID assigned by WeChat Pay
Note: Only for Institutional 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 for Institutional mode
Example: wx8888888888888888

Sub-merchant APPID

sub_appid

string[1,32]

Body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform
When Quick pay or Native Payment or Official account payment, please use appid of the merchant’s official account.
When Mini program payment, please use the appid of the merchant’s mini program.
When In-APP payment, please use the appid of the merchant’s APP.
Note: Only for Institutional mode
Example: wx8888888888888888

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]

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]

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]

Body no_credit - Credit card cannot be used for payment
Example: no_credit

Start time of a transaction

time_start

string[1,64]

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]

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

Body Payer information. For more information.

Payer

Order amount

amount

object

Yes

Body Information on the order amount. For more information, see the description below.

Order amount

Scenario information

scene_info

object

Yes

Body The scenario information object. For more information, see the description below.

Scenario information

Discount feature

detail

object

Body Discount feature info. For more information, see the description below.

Discount feature

Request Example：

Institution Mode

1{
2    "sp_appid": "wx2421b1c4370ec43b",
3    "sp_mchid": "10000100",  
4    "sub_mchid": "20000100",
5    "out_trade_no": "20150806125346",
6    "merchant_category_code": "1011",
7    "notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
8    "trade_type": "MWEB",
9    "amount": {
10      "total": 10000,
11      "currency" : "HKD"
12    },
13    "attach": "Payment test",
14    "description": "H5 payment test",
15    "goods_tag": "",
16    "detail" : {
17        "cost_price": 10000,
18        "receipt_id" : "1234",
19        "goods_detail": [
20          {
21              "goods_id":"iphone6s_16G",
22              "wxpay_goods_id":"1001",
23              "goods_name":"iPhone6s 16G",
24              "quantity":1,
25              "price":528800
26          }
27        ]
28    },
29    "scene_info": {
30      "payer_client_ip" : "14.23.150.211",
31      "device_ip" : "59.37.125.32",
32      "device_id" : "013467007045764",
33      "operator_id": "P001",
34      "store_info" : {
35        "id": "SZTX001"
36      }
37    }
38}

Common Mode

1{
2    "appid": "wx2421b1c4370ec43b",
3    "mchid": "10000100",  
4    "out_trade_no": "20150806125346",
5      "merchant_category_code": "1011",
6    "payer" : {
7      "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
8      },
9    "notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
10    "trade_type": "MWEB",
11    "amount": {
12      "total": 10000,
13      "currency" : "HKD"
14    },
15    "attach": "Payment test",
16    "description": "H5 payment test",
17    "goods_tag": "",
18    "detail" : {
19        "cost_price": 10000,
20        "receipt_id" : "1234",
21        "goods_detail": [
22          {
23              "goods_id":"iphone6s_16G",
24              "wxpay_goods_id":"1001",
25              "goods_name":"iPhone6s 16G",
26              "quantity":1,
27              "price":528800
28          }
29        ]
30    },
31    "scene_info": {
32      "payer_client_ip" : "14.23.150.211",
33      "device_ip" : "59.37.125.32",
34      "device_id" : "013467007045764",
35      "operator_id": "P001",
36      "store_info" : {
37        "id": "SZTX001"
38      }
39    }
40}

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=wx2016121516420242444321ca0631331346&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

It is returned when code is PARAM_ERROR. Details will be described below.

Detailed error description

Response Example:

SUCCESS

1{
2    "mweb_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016121516420242444321ca0631331346&package=1405458241"
3}

ERROR

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

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.