查询订单

更新时间：2026.05.21

1. 场景说明

该接口提供所有微信支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。

需要调用查询接口的情况：

1）当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；

2）调用支付接口后，返回系统错误或未知交易状态情况；

3）调用被扫支付 API，返回 USERPAYING 的状态；

4）调用关单或撤销接口 API 之前，需确认支付状态。

2. 接口说明

2.1 请求参数

字段名	变量名	是否必填	类型	示例值	描述
公众账号 ID	appid	是	String(32)	wx8888888888888888	微信分配的公众账号 ID。
子商户公众账号 ID	sub_appid	否	String(32)	wx8888888888888888	微信分配的子商户公众账号 ID。
商户号	mch_id	是	String(32)	1900000109	微信支付分配的商户号。
子商户号	sub_mch_id	是	String(32)	1900000109	微信支付分配的子商户号。
渠道商商户号	channel_id	是	String(32)	19000001	微信支付分配给收单服务商的 ID。
商户订单号	out_trade_no	是	String(32)	12121217752501201407033233368010	原交易的商户订单号，32 个字符以内、可包含字母、数字、下划线；需保证在商户端不重复。
网联 IDC 标识	idc_flag	是	String(2)	10	交易发往的网联条码支付 IDC 标识，具体规则见 4.8 网联条码支付 IDC 标识。
随机字符串	nonce_str	是	String(32)	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	随机字符串，不长于 32 位。推荐随机数生成算法。
签名	sign	是	String(512)	C380BEC2BFD727A4B6845133519F3AD6	签名。

2.2 响应参数

字段名	变量名	是否必填	类型	示例值	描述
返回状态码	return_code	是	String(16)	SUCCESS	SUCCESS/FAIL。此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断。
返回信息	return_msg	否	String(128)	签名失败	返回信息，如非空，为错误原因。签名失败。参数格式校验错误。

以下字段在return_code为SUCCESS的时候有返回：

字段名	变量名	是否必填	类型	示例值	描述
公众账号 ID	appid	是	String(32)	wx8888888888888888	调用接口提交的公众账号 ID。
商户号	mch_id	是	String(32)	1900000109	调用接口提交的商户号。
子商户公众账号 ID	sub_appid	否	String(32)	wx8888888888888888	调用接口提交的子商户公众账号 ID。
子商户号	sub_mch_id	是	String(32)	1900000109	调用接口提交的子商户号。
随机字符串	nonce_str	是	String(32)	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	网联返回的随机字符串。
签名	sign	是	String(512)	C380BEC2BFD727A4B6845133519F3AD6	网联返回的签名。
业务结果	result_code	是	String(16)	SUCCESS	SUCCESS/FAIL。
错误代码	err_code	否	String(32)	SYSTEMERROR	请参见 5.1.2.3 错误码
错误代码描述	err_code_des	否	String(128)	系统错误	错误返回的信息描述。

以下字段在return_code、result_code和trade_state都为SUCCESS时有返回，如trade_state不为SUCCESS，则只返回out_trade_no（必传）和attach（选传）：

字段名	变量名	是否必填	类型	示例值	描述
设备号	`device_info`	否	`String(32)`	`013467007045764`	微信支付分配的终端设备号。
用户标识	`openid`	否	`String(128)`	`Y`	用户在商户 `appid` 下的唯一标识。
用户子标识	`sub_openid`	否	`String(128)`	`Y`	子商户 `appid` 下用户唯一标识。
交易类型	`trade_type`	是	`String(16)`	`MICROPAY`	调用接口提交的交易类型，取值如下：`JSAPI`、`NATIVE`、`APP`、`MICROPAY`、`FACEPAY`、`MINIPROGRAM`、`SCANNEDPOS`。
交易状态	`trade_state`	是	`String(32)`	`SUCCESS`	交易状态：`SUCCESS`- 支付成功`REFUND`- 转入退款`NOTPAY`- 未支付`CLOSED`- 已关闭`REVOKED`- 已撤销（刷卡支付）`USERPAYING`- 用户支付中`PAYERROR`- 支付失败（其他原因，如银行返回失败）`ACCEPT`- 已受理
付款银行	`bank_type`	是	`String(32)`	`CMC`	银行类型，采用字符串类型的银行标识。
优惠功能	`promotion_detail`	否	`List`	-	优惠功能信息，使用 JSON 数组格式，详细说明见下文。
标价金额	`total_fee`	否	`Int`	`888`	订单总金额，单位为分，只能为整数。
标价币种	`fee_type`	否	`String(16)`	`CNY`	符合 ISO 4217 标准的三位字母代码，默认人民币：`CNY`。
应结订单金额	`settlement_total_fee`	否	`Int`	`100`	当订单使用了免充值型优惠券后返回该参数，应结订单金额 = 订单金额 - 免充值优惠券金额。
现金支付金额	`cash_fee`	是	`Int`	`100`	订单现金支付金额。
现金支付币种	`cash_fee_type`	否	`String(16)`	`CNY`	符合 ISO 4217 标准的三位字母代码，默认人民币：`CNY`。
网联订单号	`transaction_id`	是	`String(32)`	`1217752501201407033233368018`	网联订单号。
商户订单号	`out_trade_no`	是	`String(32)`	`12121217752501201407033233368010`	原交易的商户订单号，32 个字符以内、可包含字母、数字、下划线；需保证在商户端不重复。
商家数据包	`attach`	否	`String(100)`	`123456`	商家数据包，原样返回。
支付完成时间	`time_end`	是	`String(14)`	`20141030133525`	订单生成时间，格式为`yyyyMMddHHmmss`。如 2009 年 12 月 25 日 9 点 10 分 10 秒表示为`20091225091010`。
交易状态描述	`trade_state_desc`	是	`String(256)`	`支付失败，请重新下单支付`	对当前查询订单状态的描述和下一步操作的指引。
代金券金额	`coupon_fee`	否	`Int`	`100`	“代金券” 金额 <= 订单金额，订单金额 -“代金券” 金额 = 现金支付金额。
关联交易清算机构标识	`clearing_institution_code`	否	`String(2)`	`01`	账户侧清算机构编码：`01` 银联；`02` 网联；`03` 连通；
关联流水号	`bindtrx_id`	否	`String(64)`	`1217752501201407033233368018`	关联快捷流水号。
场景信息	`scene_info`	否	`String(256)`	-	该字段用于上报场景信息，目前支持上报实际门店信息。该字段为 JSON 对象数据。详见下文说明。
付款方用户标识	`bkpyeruse_code`	否	`String(128)`	`1234567890123`	用户在银行付款账号的标记化处理编号。

其中，promotion_detail对象列表：

字段名	变量名	是否必填	类型	示例值	描述
券 ID	`promotion_id`	是	`String(32)`	`109519`	券或者立减优惠 id。
优惠名称	`name`	否	`String(64)`	`单品惠-6`	优惠名称
优惠范围	`scope`	否	`String(32)`	`SINGLE`	`GLOBAL`- 全场代金券；`SINGLE`- 单品优惠。
优惠类型	`type`	否	`String(32)`	`DISCOUNT`	`COUPON`- 代金券，需要走结算资金的充值型代金券（境外商户券币种与支付币种一致）；`DISCOUNT`- 优惠券，不走结算资金的免充值型优惠券（境外商户券币种与标价币种一致）。
优惠券面额	`amount`	否	`Int`	`5`	用户享受优惠的金额（优惠券面额 = 微信出资金额 + 商家出资金额 + 其他出资方金额）。
活动 ID	`activity_id`	是	`String(32)`	`931386`	在微信商户后台配置的批次 ID。
微信出资	`wxpay_contribute`	否	`String(32)`	`0`	特指由微信支付商户平台创建的优惠，出资金额等于本项优惠总金额，单位为分。
商户出资	`merchant_contribute`	否	`String(32)`	`0`	其他出资方出资金额，单位为分。
其他出资	`other_contribute`	否	`String(32)`	`5`	其他出资方出资金额，单位为分。
单品列表	`goods_detail`	是	`String`	示例见下文	单品信息，使用 Json 数组格式。

scene_info.store_info 字段说明：

字段名	变量名	是否必填	类型	示例值	描述
门店 id	`id`	否	`String(32)`	`SZTX001`	门店唯一标识。
商户自定义编码	`out_id`	否	`String(64)`	`example_out_id`	商户系统门店编码。

goods_detail字段说明：

字段名	变量名	是否必填	类型	示例值	描述
商品编码	`goods_id`	是	`String(32)`	`商品编码`	由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。
商品备注	`goods_remark`	否	`String(128)`	`1001`	`goods_remark` 为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置。
商品优惠金额	`discount_amount`	是	`Int`	`100`	单品的总优惠金额，单位为：分。
商品数量	`quantity`	是	`Int`	`1`	用户购买的数量。
商品价格	`price`	是	`Int`	`528800`	单位为：分。如果商户有优惠，需传输商户优惠后的单价（例如：用户对一笔 100 元的订单使用了商场发的优惠券 100-50，则活动商品的单价应为原单价 - 50）。

3. 错误码

名称	描述	原因	解决方案
ORDERNOTEXIST	此交易订单号不存在	查询系统中不存在此交易订单号	该 API 只能查提交支付交易返回成功的订单，请商户检查需要查询的订单号是否正确
SYSTEMERROR	系统错误	后台系统返回错误	系统异常，请再调用发起查询

文档是否有帮助