商户订单号查询订单

更新时间:2025.01.16

订单支付成功后,商户可使用微信订单号查询订单或商户订单号查询订单;若订单未支付,则只能使用商户订单号查询订单。

接口说明

支持商户:【普通服务商】【平台商户】

请求方式:【GET】/v3/pay/partner/transactions/out-trade-no/{out_trade_no}

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header HTTP头参数

Authorization  必填 string

请参考签名认证生成认证信息


Accept  必填 string

请设置为application/json


path 路径参数

out_trade_no  必填 string(32)

【商户订单号】 服务商下单时传入的服务商系统内部订单号。


query 查询参数

sp_mchid  必填 string(32)

【服务商商户号】服务商下单时传入的服务商商户号sp_mchid。


sub_mchid  必填 string(32)

【子商户号(也叫特约商户号)】 服务商下单时传入的子商户号sub_mchid。

请求示例

Java
Go
curl

需配合微信支付工具库 WXPayUtility 使用,请参考 Java 

1package com.java.demo;
2
3import com.google.gson.annotations.Expose;
4import com.google.gson.annotations.SerializedName;
5import com.java.utils.WXPayUtility; // 引用微信支付工具库 参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777
6import java.io.IOException;
7import java.io.UncheckedIOException;
8import java.security.PrivateKey;
9import java.security.PublicKey;
10import java.util.ArrayList;
11import java.util.HashMap;
12import java.util.List;
13import java.util.Map;
14import okhttp3.MediaType;
15import okhttp3.OkHttpClient;
16import okhttp3.Request;
17import okhttp3.RequestBody;
18import okhttp3.Response;
19
20/**
21 * 微信支付商户订单号查询订单
22 */
23public class PartnerQueryByOutTradeNo {
24  private static String HOST = "https://api.mch.weixin.qq.com";
25  private static String METHOD = "GET";
26  private static String PATH = "/v3/pay/partner/transactions/out-trade-no/{out_trade_no}";
27
28  public static void main(String[] args) {
29    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
30    PartnerQueryByOutTradeNo client = new PartnerQueryByOutTradeNo(
31        "填入 商户号",                  // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考https://pay.weixin.qq.com/doc/v3/partner/4013080340
32        "填入 商户API证书序列号",       // 商户API证书序列号,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013058924
33        "填入 商户API证书私钥文件路径", // 商户API证书私钥文件路径,本地文件路径
34        "填入 微信支付公钥ID",          // 微信支付公钥ID,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013038589
35        "填入 微信支付公钥文件路径"     // 微信支付公钥文件路径,本地文件路径
36    );
37
38    PartnerQueryByOutTradeNoRequest request = new PartnerQueryByOutTradeNoRequest();
39    request.outTradeNo = "1217752501201407033233368018";
40    request.spMchid = "1230000109";
41    request.subMchid = "1900000109";
42    try {
43      PartnerAPIv3PartnerQueryResponse response = client.run(request);
44
45      // TODO: 请求成功,继续业务逻辑
46      System.out.println(response);
47    } catch (WXPayUtility.ApiException e) {
48      // TODO: 请求失败,根据状态码执行不同的逻辑
49      e.printStackTrace();
50    }
51  }
52
53  public PartnerAPIv3PartnerQueryResponse run(PartnerQueryByOutTradeNoRequest request) {
54    String uri = PATH;
55    uri = uri.replace("{out_trade_no}", WXPayUtility.urlEncode(request.outTradeNo));
56    Map<String, Object> args = new HashMap<>();
57    args.put("sp_mchid", request.spMchid);
58    args.put("sub_mchid", request.subMchid);
59    uri = uri + "?" + WXPayUtility.urlEncode(args);
60
61    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
62    reqBuilder.addHeader("Accept", "application/json");
63    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
64    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null));
65    reqBuilder.method(METHOD, null);
66    Request httpRequest = reqBuilder.build();
67
68    // 发送HTTP请求
69    OkHttpClient client = new OkHttpClient.Builder().build();
70    try (Response httpResponse = client.newCall(httpRequest).execute()) {
71      String respBody = WXPayUtility.extractBody(httpResponse);
72      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
73        // 2XX 成功,验证应答签名
74        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
75                                      httpResponse.headers(), respBody);
76
77        // 从HTTP应答报文构建返回数据
78        return WXPayUtility.fromJson(respBody, PartnerAPIv3PartnerQueryResponse.class);
79      } else {
80        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
81      }
82    } catch (IOException e) {
83      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
84    }
85  }
86
87  private final String mchid;
88  private final String certificateSerialNo;
89  private final PrivateKey privateKey;
90  private final String wechatPayPublicKeyId;
91  private final PublicKey wechatPayPublicKey;
92
93  public PartnerQueryByOutTradeNo(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
94    this.mchid = mchid;
95    this.certificateSerialNo = certificateSerialNo;
96    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
97    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
98    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
99  }
100
101  public static class CommRespAmountInfo {
102    @SerializedName("total")
103    public Long total;
104
105    @SerializedName("payer_total")
106    public Long payerTotal;
107
108    @SerializedName("currency")
109    public String currency;
110
111    @SerializedName("payer_currency")
112    public String payerCurrency;
113  }
114
115  public static class CommRespSceneInfo {
116    @SerializedName("device_id")
117    public String deviceId;
118
119    @SerializedName("store_info")
120    public StoreInfo storeInfo;
121  }
122
123  public static class GoodsDetailInPromotion {
124    @SerializedName("goods_id")
125    public String goodsId;
126
127    @SerializedName("quantity")
128    public Integer quantity;
129
130    @SerializedName("unit_price")
131    public Long unitPrice;
132
133    @SerializedName("discount_amount")
134    public Long discountAmount;
135
136    @SerializedName("goods_remark")
137    public String goodsRemark;
138  }
139
140  public static class PartnerAPIv3PartnerQueryResponse {
141    @SerializedName("sp_appid")
142    public String spAppid;
143
144    @SerializedName("sp_mchid")
145    public String spMchid;
146
147    @SerializedName("sub_appid")
148    public String subAppid;
149
150    @SerializedName("sub_mchid")
151    public String subMchid;
152
153    @SerializedName("out_trade_no")
154    public String outTradeNo;
155
156    @SerializedName("transaction_id")
157    public String transactionId;
158
159    @SerializedName("trade_type")
160    public String tradeType;
161
162    @SerializedName("trade_state")
163    public String tradeState;
164
165    @SerializedName("trade_state_desc")
166    public String tradeStateDesc;
167
168    @SerializedName("bank_type")
169    public String bankType;
170
171    @SerializedName("attach")
172    public String attach;
173
174    @SerializedName("success_time")
175    public String successTime;
176
177    @SerializedName("payer")
178    public PartnerCommRespPayerInfo payer;
179
180    @SerializedName("amount")
181    public CommRespAmountInfo amount;
182
183    @SerializedName("scene_info")
184    public CommRespSceneInfo sceneInfo;
185
186    @SerializedName("promotion_detail")
187    public List<PromotionDetail> promotionDetail;
188  }
189
190  public static class PartnerQueryByOutTradeNoRequest {
191    @SerializedName("sp_mchid")
192    @Expose(serialize = false)
193    public String spMchid;
194
195    @SerializedName("sub_mchid")
196    @Expose(serialize = false)
197    public String subMchid;
198
199    @SerializedName("out_trade_no")
200    @Expose(serialize = false)
201    public String outTradeNo;
202  }
203
204  public static class StoreInfo {
205    @SerializedName("id")
206    public String id;
207
208    @SerializedName("out_id")
209    public String outId;
210  }
211
212  public static class PartnerCommRespPayerInfo {
213    @SerializedName("sp_openid")
214    public String spOpenid;
215
216    @SerializedName("sub_openid")
217    public String subOpenid;
218  }
219
220  public static class PromotionDetail {
221    @SerializedName("coupon_id")
222    public String couponId;
223
224    @SerializedName("name")
225    public String name;
226
227    @SerializedName("scope")
228    public String scope;
229
230    @SerializedName("type")
231    public String type;
232
233    @SerializedName("amount")
234    public Long amount;
235
236    @SerializedName("stock_id")
237    public String stockId;
238
239    @SerializedName("wechatpay_contribute")
240    public Long wechatpayContribute;
241
242    @SerializedName("merchant_contribute")
243    public Long merchantContribute;
244
245    @SerializedName("other_contribute")
246    public Long otherContribute;
247
248    @SerializedName("currency")
249    public String currency;
250
251    @SerializedName("goods_detail")
252    public List<GoodsDetailInPromotion> goodsDetail;
253  }
254}

 

应答参数

200 OK

sp_appid  必填 string(32)

【服务商APPID】服务商下单时传入的服务商sp_appid。


sp_mchid  必填 string(32)

【服务商商户号】服务商下单时传入的服务商商户号sp_mchid。


sub_appid  选填 string(32)

【子商户APPID】服务商下单时传入的子商户sub_appid,若下单未传该参数,则不会返回。


sub_mchid  必填 string(32)

【子商户号】务商下单时传入的子商户号sub_mchid。


out_trade_no  必填 string(32)

【商户订单号】 服务商下单时传入的服务商系统内部订单号。


transaction_id  选填 string(32)

【微信支付订单号】 微信支付侧订单的唯一标识,订单支付成功后返回。


trade_type  选填 string(16)

【交易类型】 返回当前订单的交易类型,枚举值:

  • JSAPI:公众号支付、小程序支付

  • NATIVE:Native支付

  • APP:APP支付

  • MICROPAY:付款码支付

  • MWEB:H5支付

  • FACEPAY:刷脸支付


trade_state  必填 string(32)

【交易状态】 交易状态,详细业务流转状态处理请参考开发指引-订单状态流转图。枚举值:

  • SUCCESS:支付成功

  • REFUND:转入退款

  • NOTPAY:未支付

  • CLOSED:已关闭

  • REVOKED:已撤销(仅付款码支付会返回)

  • USERPAYING:用户支付中(仅付款码支付会返回)

  • PAYERROR:支付失败(仅付款码支付会返回)


trade_state_desc  必填 string(256)

【交易状态描述】 对交易状态的详细说明。


bank_type  选填 string(32)

【银行类型】 用户支付方式,订单支付成功后返回,
1、使用银行卡支付,例如工商银行借记卡,该字段返回 ICBC_DEBIT,更多银行类型请参考《银行类型对照表》。
2、使用非银行卡支付,例如余额/零钱通等,该字段统一返回OTHERS


attach  选填 string(128)

【商户数据包】服务商下单时传入的自定义数据包,用户不可见,长度不超过128字符,若下单传入该参数,则订单支付成功后此接口和支付成功回调通知以及交易账单中会原样返回;若下单未传该参数,则不会返回。


success_time  选填 string(64)

【支付完成时间】

1、定义:用户完成订单支付的时间。该参数在订单支付成功后返回。

2、格式遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONEyyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。

示例:2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。


payer  选填 object

【支付者信息】订单的支付者信息,订单支付成功后返回

属性

amount  选填 object

【订单金额】 订单金额信息。

属性

scene_info  选填 object

【场景信息】 下单时传入的支付场景描述,若下单传入该参数,则原样返回;若下单未传该参数,则不会返回。

属性

promotion_detail  选填 array[object]

【优惠功能】 代金券信息,当订单支付时,有使用代金券时,该字段将返回所使用的代金券信息。

属性

应答示例

200 OK

1{
2  "sp_appid" : "wx8888888888888888",
3  "sp_mchid" : "1230000109",
4  "sub_appid" : "wxd678efh567hg6999",
5  "sub_mchid" : "1900000109",
6  "out_trade_no" : "1217752501201407033233368018",
7  "transaction_id" : "1217752501201407033233368018",
8  "trade_type" : "JSAPI",
9  "trade_state" : "SUCCESS",
10  "trade_state_desc" : "支付失败,请重新下单支付",
11  "bank_type" : "CMC",
12  "attach" : "自定义数据",
13  "success_time" : "2018-06-08T10:34:56+08:00",
14  "payer" : {
15    "sp_openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o\t",
16    "sub_openid" : "example_sub_openid"
17  },
18  "amount" : {
19    "total" : 100,
20    "payer_total" : 100,
21    "currency" : "CNY",
22    "payer_currency" : "CNY"
23  },
24  "scene_info" : {
25    "device_id" : "013467007045764"
26    }
27  },
28  "promotion_detail" : [
29    {
30      "coupon_id" : "109519",
31      "name" : "单品惠-6",
32      "scope" : "GLOBAL",
33      "type" : "CASH",
34      "amount" : 100,
35      "stock_id" : "931386",
36      "wechatpay_contribute" : 0,
37      "merchant_contribute" : 0,
38      "other_contribute" : 0,
39      "currency" : "CNY",
40      "goods_detail" : [
41        {
42          "goods_id" : "M1006",
43          "quantity" : 1,
44          "unit_price" : 100,
45          "discount_amount" : 1,
46          "goods_remark" : "商品备注信息"
47        }
48      ]
49    }
50  ]
51}
52

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

INVALID_REQUEST

无效请求

请根据接口返回的详细信息检查

400

MCH_NOT_EXISTS

商户号不存在

请检查商户号是否正确,商户号获取方式请参考:服务商模式开发必要参数说明

401

SIGN_ERROR

签名错误

请检查签名参数和方法是否都符合签名算法要求,参考:如何生成签名

403

RULE_LIMIT

业务规则限制

因业务规则限制请求频率,请查看接口返回的详细信息

403

TRADE_ERROR

交易错误

因业务原因交易失败,请查看接口返回的详细信息

404

ORDER_NOT_EXIST

订单不存在

请检查商户订单号是否下单成功

429

FREQUENCY_LIMITED

频率超限

请降低请求接口频率

500

SYSTEM_ERROR

系统错误

系统异常,请用相同参数重新调用

 

 

反馈
咨询
目录
置顶