API Dictionary / JSAPI Payment / Query Order API

Query Order API

Latest update time：2022.08.04 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.

Tips：

Scenarios where the Query API should be called:

• The merchant system does not receive any payment notification due to an error of the merchant backend, network, server, etc.

• A system error is returned or the transaction status is unknown after the payment API is called.

• The USERPAYING status is returned after the Quick Pay API is called.

• The payment status needs to be confirmed before the order closure or cancellation API is called.

1. API intro

Applicable object:Common modeInstitutional mode

Request URL： https://apihk.mch.weixin.qq.com/v3/global/transactions/id/{id}
OR
https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/{out_trade_no}
Note: The {id} in the URL refers to the actual WeChat order No., while the {out_trade_no} refers to the actual merchant order No., either of which is called.

Request method: GET

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	Query Merchant ID assigned by WeChat Pay Note: Only forCommon mode Example: 1900000109
Sub-merchant ID	sub_mchid	string[1,32]	Yes	Query 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
Merchant order No.	out_trade_no	string[1,32]	Choose one	PathOrder No. corresponding to the original payment transaction Example: 1217752501201407033233368018
WeChat Pay order No.	id	string[1,32]	Choose one	PathWeChat order No. corresponding to the original payment transaction Example: 4200000000002106108200370006

Request Eample

Common modeInstitutional mode


https://apihk.mch.weixin.qq.com/v3/global/transactions/id/4200000000002104083200000488?mchid=1900000109


https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/1217752501201407033233368018?sub_mchid =1900000109&sp_mchid =1900000100


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. Response Parameters

Response for successful request:

Name

Variable Name

Type

Required

Description

Merchant ID

mchid

string[1,32]

Yes

Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example: 1900000109

APPID

appid

string[1,32]

Yes

APPID corresponding to the mobile app applied for by the merchant on the WeChat Open Platform
Note: Only forCommon mode
Example: wx8888888888888888

Institution's Merchant ID

sp_mchid

string[1,32]

Yes

Institution's Merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example: 1900000100

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Sub-merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example: 1900000109

Organization APPID

sp_appid

string[1,32]

Yes

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]

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 forInstitutional mode
Example: wx8888888888888888

Merchant order No.

out_trade_no

string[1,32]

Yes

Returned merchant's order No.
Example: 1217752501201407033233368018

WeChat Pay order No.

string[1,32]

Yes

WeChat Pay order No.
Example: 4200752501201407033233368018

Merchant data

attach

string[1,127]

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

Transaction type

trade_type

string[1,16]

Yes

In-NATIVE Pay
Example: NATIVE

Paying bank

bank_type

string[1,32]

Yes

Bank type, which is the bank ID in string format. See Bank Type for the list of values.
Example: CMC

Payment completion time

success_time

string[1,64]

Yes

The time when the order is paid successfully, 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

Transaction status

trade_state

string[1,32]

Yes

SUCCESS : Payment successful
REFUND : Transferred to refund
NOTPAY : Unpaid
CLOSED : Closed
REVOKED : Revoked (Quick Pay)
USERPAYING : Payment in progress
PAYERROR : Payment failed(other reasons, for example, failed to be returned by the bank)
Example: SUCCESS

Transaction status description

trade_state_desc

string[1,256]

Yes

Descriptions on the current order status and instructions for the next operation.
Example: Payment failed. Place another order and pay it again.

Payer

payer

object

Yes

Payer information. For more information, see the description below.

Name	Variable Name	Type	Required	Description
User ID	openid	string[1,128]	No	The unique user ID corresponding to the merchant's appid. It is returned only when appid is passed. Note: Only forCommon mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Institution user ID	sp_openid	string[1,128]	No	The unique user ID corresponding to the merchant's sp_appid. It is returned only when sp_appid is passed. Note: Only forInstitutional mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Sub-merchant user ID	sub_openid	string[1,128]	No	The unique user ID corresponding to the merchant's sub_appid. It is returned only when sub_appid is passed. Note: Only forInstitutional mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

pack up

Order amount

amount

object

Yes

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

Name

Variable Name

Type

Required

Description

Order 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

User's payment amount

payer_total

int

Yes

The actual amount paid by the user. The minimum unit of the currency can only be an integer. See "Transaction amount" for details.
Example: 888

Priced currency

currency

string[1,16]

Yes

Three-letter code in accordance with ISO 4217.
Example: CNY

User payment currency

payer_currency

string[1,16]

Yes

Three-letter code in accordance with ISO 4217.
Example: HKD

Exchange rate information

exchange_rate

object

The object of the exchange rate information. For more information, see the description below.

Name	Variable Name	Type	Required	Description
Exchange rate type	type	string[1,32]	No	SETTLEMENT_RATE,which is the exchange rate between the priced currency and the settlement currency Example: SETTLEMENT_RATE
Exchange rate value	rate	int	No	The rate value is the exchange rate multiplied by the 8th power of 10. If the priced currency is the same as the settlement currency, then the exchange rate is 1, and the exchange rate value is 100,000,000; if the priced currency is different from the settlement currency, for example, the exchange rate between USD and CNY is 6.5, then the exchange rate value is 650,000,000. Example: 80000000

pack up

Discount feature

promotion_detail

array

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

Name

Variable Name

Type

Required

Description

Voucher ID

promotion_id

string[1,32]

Yes

Voucher or discount ID
Example: 109519

Discount name

name

string[1,64]

Discount name
Example: Single-item discount-6

Discount range

scope

string[1,32]

GLOBAL - All-item voucher
SINGLE - Single-item discount
Example: SINGLE

Discount type

type

string[1,32]

COUPON - Vouchers, which are a kind of top-up vouchers that require fund settlement (the voucher currency of overseas merchants is the same as the payment currency)
DISCOUNT - Discount vouchers, which are a kind of top-up-free discount vouchers that require no fund settlement (the voucher currency of overseas merchants is the same as the priced currency).
Example: DISCOUNT

Discount voucher price

amount

int

Yes

The discount amount
Example: 5

Discount currency

currency

string[1,16]

Yes

Three-letter code in accordance with ISO 4217.
Example: HKD

Activity ID

activity_id

string[1,32]

Batch ID set up by the backend of the WeChat merchant
Example: 931386

Contribution by WeChat

wxpay_contribute_amount

int

It is the discount provided by the WeChat Pay Merchant Platform, and the total contribution is equal to the total amount of this discount.
Example: 0

Contribution by the merchant

merchant_contribute_amount

int

It is the discount provided by the merchant, and the total contribution is equal to the total amount of this discount.
Example: 0

Other contributions

other_contribute_amount

int

The contributions made by other contributors
Example: 5

Product details

goods_detail

array

Product information submitted in JSON format

Name	Variable Name	Type	Required	Description
Product code	goods_id	string[1,32]	Yes	It consists of a combination of uppercase and lowercase letters, numbers, hyphens and underscores. Example: Product code
Product remarks	goods_remark	string[1,128]	No	goods_remark is a remark field that is returned unchanged. It is set when the voucher is configured in the WeChat backend. Example: 1001
Product discount amount	discount_amount	int	Yes	Total discount amount of a single item Example: 100
Number of products	quantity	int	Yes	Number of products purchased by a user Example: 1
Product 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 paper voucher of 50 CNY Off 100 CNY issued by the shop to an order of 100 CNY, the discounted price should be the original price 100 CNY minus 50 CNY). Example: 528800

pack up

Note: goods_remark is a remark field that is returned unchanged. goods_tag is an order discount tag to distinguish whether an order can be discounted. Both fields are set when the voucher is configured in the WeChat backend.

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.

Name	Variable Name	Type	Required	Description
The location of incorrect parameter	field	string[1,256]	Yes	If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Value of the incorrect parameter	value	string[1,256]	Yes	Value of the incorrect parameter
Cause of error	issue	string[1,256]	Yes	Cause of error
Location of the incorrect parameter	location	string[1,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

pack up

Response Example:

SUCCESS ERROR


{
	"id": "4200752501201407033233368018",
	"appid": "wx2421b1c4370ec43b",
	"mchid": "20000100",
	"out_trade_no": "20150806125346",
	"payer": {
		"openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
	},
	"amount": {
		"total": 528800,
		"currency": "HKD",
		"payer_total": 518799,
		"payer_currency": "CNY",
		"exchange_rate": {
			"type": "SETTLEMENT_RATE",
			"rate": 8000000
		}
	},
	"trade_type": "NATIVE",
	"trade_state": "SUCCESS",
	"trade_state_desc": "Payment successful",
	"bank_type": "CCB_DEBIT",
	"attach": "Payment test",
	"success_time": "2018-06-08T10:34:56+08:00",
	"promotion_detail": [{
		"promotion_id": "109519",
		"name": "Single-item discount-6",
		"scope": "SINGLE",
		"type": "DISCOUNT",
		"amount": 1,
		"currency": "HKD",
		"activity_id": "931386",
		"wechatpay_contribute_amount": 1,
		"merchant_contribute_amount": 0,
		"other_contribute_amount": 0,
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"goods_remark": "Product remarks",
			"quantity": 1,
			"price": 528800
		}]
	}]
}


{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

4. Error Codes

Error Message	Description	Solution
ORDER_NOT_EXIST	This transaction order No. does not exist.	The API can only be used for checking orders where transactions return successfully after payment submission. Check whether the order no. to be viewed is correct.
SYSTEM_ERROR	System error	System error. Please call the API again to initiate the query.

Page Navigation

Language

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Query Order API

1. API intro

2. Request Parameters

Request Eample

3. Response Parameters

Response for successful request:

Response for failed request:

Response Example:

4. Error Codes