Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Order Placement API

Latest update time:2022.03.10 Release notes


This API can be used to query all WeChat Pay orders. Merchants can use the Query Order API to query the order status and then complete subsequent business logic.


API intro

Request URL: https://api.mch.weixin.qq.com/hk/v3/transactions/jsapi

Request method: POST

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3


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.

Request Parameters

Name Variable Name Type Required Description
Merchant ID mchid string(32) Yes body Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example:1900000109
APPID appid string(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(32) Yes body Sub-merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000109
Institution's Merchant ID sp_mchid string(32) Yes body Institution's Merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000100
Organization APPID sp_appid string(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(32) No

body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform
When Quick pay or QR code 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 forInstitutional mode
Example:wx8888888888888888

Product description description string(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(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(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(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(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(16) Yes body OfficialPayment:JSAPI
Native Payment: NATIVE
In-APP payment: APP
H5 payment: MWEB
QuickPay: MICROPAY
MiniProgram payment: JSAPI
Example:APP
Payment method limit_pay string(32) No bodyno_credit - Credit card cannot be used for payment
Example:no_credit
Start time of a transaction time_start string(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(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(16) Yes body Merchant category codes,see Merchant category codes
Example:1011
+ Payer payer object No body Payer information. For more information.
Name Variable Name Type Required Description
User ID openid string(128) No The unique user ID corresponding to the merchant's appid. The [web authorization] API is required to be called to obtain the user's openid before order placement.
Note: Only forCommon mode
Example:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
User ID (service provider) sp_openid string(128) No The unique user ID corresponding to the service provider's sp_appid. Either openid or sub_openid can be passed. If sub_openid is selected, sub_appid must also be passed. The [web authorization] API is required to be called to obtain the user's openid before order placement.
Note: Only forInstitutional mode
Example:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
User ID (contracted merchant) sub_openid string(128) No The unique user ID corresponding to the sub-merchant's sub_appid. Either openid or sub_openid can be passed. If sub_openid is selected, sub_appid must also be passed. The [web authorization] API is required to be called to obtain the user's openid before order placement.
Note: Only forInstitutional mode
Example:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
+Order amount amount object Yes body Information on the order amount. For more information, see the description below.
Name Variable Name Type Required Description
Total amount total int Yes The total order amount. The minimum unit of the currency can only be an integer. See "Transaction amount" for details.
Example:888
Currency type currency string(16) Yes Three-letter code in accordance with ISO 4217.
Note:Currently the currency can only be set as HKD.
Example:HKD
+ Scenario information scene_info object No body The scenario information object. For more information, see the description below.
Name Variable Name Type Required Description
Merchant's device No. device_id string(32) No Terminal device No. (which is customized by the merchant, such as store No.)
Example:013467007045764
Merchant's device IP device_ip string(40) No The IP of the merchant's device, which is the public network egress IP and supports IPV6.
Example:128.0.0.1
User terminal IP payer_client_ip string(40) No The IP of the user's device, which is the public network egress IP and supports IPV6
Example:128.0.0.1
Operator ID operator_id string(32) No Cashier ID, customized by the merchant
Example:123145
+ Merchants' store information store_info object No Store information object. For more information, see the description below.
Name Variable Name Type Required Description
No. id string(32) No Merchant store ID
Example:0001
Name name string(32) Yes Tencent Building Branch
Example:Merchant store name
Address address string(64) Yes No. 10000, No.1, Keji Road, Science and Technology Park, Nanshan District, Shenzhen, Guangdong
Example:Detailed address of the merchant's store
+ Discount feature detail object No body Discount feature info. For more information, see the description below.
Name Variable Name Type Required Description
Original order price cost_price int No 1.The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order.
2.If the original order price is different from the payment amount, the discount is not available.
3.This field is mainly used to prevent split payment for multiple discounts. This parameter is not required for normal payment.
Example:608800
Product receipt ID receipt_id string(32) No Merchant receipt ID
Example:wx123
+ Product details goods_detail Array No Product details, submitted in JSON array format. See the table below.
Name Variable Name Type Required Description
Product code goods_id string(32) Yes It consists of a combination of uppercase and lowercase letters, numbers, hyphens and underscores.
Example:Product code
Product code on WeChat wxpay_goods_id string(32) No Unified product No. defined by WeChat Pay (optional)
Example:1001
Product name goods_name string(256) No Actual product name
Example:iPhone6s 16G
Number of products quantity int Yes Number of products purchased by a user
Example:1
Unit price price int Yes If the merchant provides a discount, the discounted unit price should be transferred (for example, if the user has applied a voucher of 50 CNY off 100 CNY issued by the shop to an order of 100 CNY, the discounted price should be the original 100 CNY minus 50 CNY).
Example:528800

For example:


{
	"sp_appid": "wx2421b1c4370ec43b",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"sub_appid": "wx352671b037b437ec",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "1011",
	"payer": {
		"sub_openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
	},
	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
	"trade_type": "JSAPI",
	"amount": {
		"total": 10000,
		"currency": "HKD"
	},
	"attach": "Payment test",
	"description": "Miniprogramm Pay test",
	"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"
		}
	}
}

{
	"appid": "wx2421b1c4370ec43b",
	"mchid": "10000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "1011",
	"payer": {
		"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
	},
	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
	"trade_type": "JSAPI",
	"amount": {
		"total": 10000,
		"currency": "HKD"
	},
	"attach": "Payment test",
	"description": "Miniprogramm Pay test",
	"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"
		}
	}
}

    
{
JAVA示例代码
}
    

Returned Result

Response for failed request:

Name Variable Name Type Required Description
Returned status code code string(32) Yes Error code. See the error code list for the enumerated values.
Example:INVALID_REQUEST
Returned message message string(256) Yes Returned message. It indicates the reason for the error if not empty.
Example:Parameter format verification error
+ Detailed error description detail object No It is returned when code is PARAM_ERROR. Details will be described below.
Name Variable Name Type Required Description
Location of the incorrect parameter field string(256) Yes Enter the JSON Pointer pointing to the invalid parameter when it is in the JSON of the request body;
Enter the variable name of the parameter when the invalid parameter is in the request URL or querystring.
Example:#/properties/payer
Value of the incorrect parameter value string(256) Yes Value of the incorrect parameter
Example:1346177081915535577
Cause of error issue string(256) Yes Cause of error
Example:It is different from ALLOF schema
Location of the incorrect parameter location string(256) No body:The incorrect parameter is in the JSON for request body
url:The incorrect parameter is in the request URL
query:The incorrect parameter is in the querystring of the request
Example:body

Response for successful request

Name Variable Name Type Required Description
Prepayment transaction session prepay_id string(64) Yes Prepayment session ID generated by WeChat, which is used in subsequent API calls. The value is valid for 2 hours.
Example:wx201410272009395522657a690389285100

For example:

{
    "prepay_id": "wx201411101639507cbf6ffd8b0779950874"
}

{
"code":"INVALID_REQUEST",
"message":"Parameter format verification error",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"It is different from ALLOF schema",
    "location":"body"
   }
}

Error Codes

Name Description Solution
NOAUTH The merchant does not have access to the API. Let the merchant to apply for access to the API.
NOTENOUGH Insufficient balance The user's account balance is insufficient. Top up or use another payment card.
ORDERPAID Merchant order paid. Merchant order paid. Other operation not needed.
ORDERCLOSED Order closed Order closed. Place a new order.
SYSTEMERROR 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.
SIGNERROR 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.


Release notes

close
V1.1
2022.03.10
1.The request parameter promotion_detail is adjusted to detail
V1.0
2020.04.30
1.Order Placement 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