Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Query Order API

Latest update time:2020.04.30 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:


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

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

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

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


API intro

Request URL: https://api.mch.weixin.qq.com/hk/v3/transactions/id/{id}?mchid=parameter value
                       OR
                      https://api.mch.weixin.qq.com/hk/v3/transactions/out-trade-no/{out_trade _no}?mchid=parameter value
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

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 query Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example:1900000109
Sub-merchant ID sub_mchid string(32) Yes query Sub-merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000109
Institution's Merchant ID sp_mchid string(32) Yes query Institution's Merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000100
Merchant order No. out_trade_no string(32) Choose one pathOrder No. corresponding to the original payment transaction
Example:1217752501201407033233368018
WeChat Pay order No. id string(32) pathWeChat order No. corresponding to the original payment transaction
Example:4200000000002106108200370006

Example:



Common mode:
https://api.mch.weixin.qq.com/hk/v3/transactions/id/1217752501201407033233368018?mchid=1900000109


Institutional mode:
https://api.mch.weixin.qq.com/hk/v3/transactions/out-trade-no/1217752501201407033233368018?sub_mchid =1900000109&sp_mchid =1900000100


    
{
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 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.
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 paramete 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
Merchant ID mchid string(32) Yes Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example:1900000109
APPID appid string(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(32) Yes Institution's Merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000100
Sub-merchant ID sub_mchid string(32) Yes Sub-merchant ID assigned by WeChat Pay
Note: Only forInstitutional mode
Example:1900000109
Organization APPID sp_appid string(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(32) No 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
Merchant order No. out_trade_no string(32) Yes Returned merchant's order No.
Example:1217752501201407033233368018
WeChat Pay order No. id string(32) Yes WeChat Pay order No.
Example:4200752501201407033233368018
Merchant data attach string(127) No 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(16) Yes In-NATIVE Pay
Example:NATIVE
Paying bank bank_type string(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(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(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(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(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(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(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
+ 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(16) Yes Three-letter code in accordance with ISO 4217.
Example:CNY
User payment currency payer_currency string(16) Yes Three-letter code in accordance with ISO 4217.
Example:HKD
+ Exchange rate information exchange_rate object No 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(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
+ Discount feature promotion_detail array No Discount feature info. For more information, see the description below.
Name Variable Name Type Required Description
Voucher ID promotion_id string(32) Yes Voucher or discount ID
Example:109519
Discount name name string(64) No Discount name
Example:Single-item discount-6
Discount range scope string(32) No GLOBAL - All-item voucher
SINGLE - Single-item discount
Example:SINGLE
Discount type type string(32) No 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(16) Yes Three-letter code in accordance with ISO 4217.
Example:HKD
Activity ID activity_id string(32) No Batch ID set up by the backend of the WeChat merchant
Example:931386
Contribution by WeChat wxpay_contribute_amount int No 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 No 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 No The contributions made by other contributors
Example:5
+ Product details goods_detail array No Product information submitted in JSON format
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 remarks goods_remark string(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

For example:

{
	"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
		}]
	}]
}

Error Codes

Name Description Solution
ORDERNOTEXIST 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.
SYSTEMERROR System error System error. Please call the API again to initiate the query.


Release notes

close
V1.0
2020.04.30
1.Query Order 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