Query Order

Update Time：2025.02.25

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 mode Institutional 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

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	Query Merchant ID assigned by WeChat Pay Note: Only for Common mode Example: 1900000109
Sub-merchant ID	sub_mchid	string[1,32]	Yes	Query Sub-merchant ID assigned by WeChat Pay Note: Only for Institutional mode Example: 1900000109
Institution's Merchant ID	sp_mchid	string[1,32]	Yes	Query Institution's Merchant ID assigned by WeChat Pay Note: Only for Institutional mode Example: 1900000100
Merchant order No.	out_trade_no	string[1,32]	Choose one	Path Order No. corresponding to the original payment transaction Example: 1217752501201407033233368018
WeChat Pay order No.	id	string[1,32]	Choose one	Path WeChat order No. corresponding to the original payment transaction Example: 4200000000002106108200370006

Request Example

Common mode

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

Institutional mode

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

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

Institution's Merchant ID

sp_mchid

string[1,32]

Yes

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

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Sub-merchant ID assigned by WeChat Pay
Note: Only for Institutional 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 for Institutional 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 for Institutional 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.

Payer

Order amount

amount

object

Yes

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

Order amount

Discount feature

promotion_detail

array

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

Discount feature

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

Product details

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.

Detailed error description

Response Example:

SUCCESS

1{
2	"id": "4200752501201407033233368018",
3	"appid": "wx2421b1c4370ec43b",
4	"mchid": "20000100",
5	"out_trade_no": "20150806125346",
6	"payer": {
7		"openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
8	},
9	"amount": {
10		"total": 528800,
11		"currency": "HKD",
12		"payer_total": 518799,
13		"payer_currency": "CNY",
14		"exchange_rate": {
15			"type": "SETTLEMENT_RATE",
16			"rate": 8000000
17		}
18	},
19	"trade_type": "NATIVE",
20	"trade_state": "SUCCESS",
21	"trade_state_desc": "Payment successful",
22	"bank_type": "CCB_DEBIT",
23	"attach": "Payment test",
24	"success_time": "2018-06-08T10:34:56+08:00",
25	"promotion_detail": [{
26		"promotion_id": "109519",
27		"name": "Single-item discount-6",
28		"scope": "SINGLE",
29		"type": "DISCOUNT",
30		"amount": 1,
31		"currency": "HKD",
32		"activity_id": "931386",
33		"wechatpay_contribute_amount": 1,
34		"merchant_contribute_amount": 0,
35		"other_contribute_amount": 0,
36		"goods_detail": [{
37			"goods_id": "iphone6s_16G",
38			"goods_remark": "Product remarks",
39			"quantity": 1,
40			"price": 528800
41		}]
42	}]
43}

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
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.