APP下单

更新时间:2025.03.31

用户在服务商或子商户(也叫特约商户)APP端选择微信支付后,服务商需调用该接口在微信支付下单,生成用于调起支付的预支付交易会话标识(prepay_id)。

接口说明

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

请求方式:【POST】/v3/pay/partner/transactions/app

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

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

请求参数

Header HTTP头参数

Authorization  必填 string

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


Accept  必填 string

请设置为application/json


Content-Type  必填 string

请设置为application/json


body 包体参数

sp_appid  必填 string(32)

【服务商APPID】服务商移动应用的唯一标识,在开放平台(移动应用)申请。此处填写的sp_appid需要与sp_mchid有绑定关系,具体请参考服务商模式开发必要参数说明


sp_mchid  必填 string(32)

【服务商商户号】是由微信支付系统生成并分配给每个服务商的唯一标识符,具体请参考服务商模式开发必要参数说明


sub_appid  选填 string(32)

【子商户APPID】子商户移动应用的唯一标识,在开放平台(移动应用)申请。此处填写的sub_appid需要与sub_mchid有绑定关系,具体请参考服务商模式开发必要参数说明


sub_mchid  必填 string(32)

【子商户号】由服务商为子商户进件后获取,具体请参考服务商模式开发必要参数说明


description  必填 string(127)

【商品描述】商品信息描述,用户微信账单的商品字段中可见(可参考APP支付示例说明-账单示意图),服务商需传递能真实代表商品信息的描述,不能超过127个字符。


out_trade_no  必填 string(32)

【商户订单号】服务商系统内部订单号,要求6-32个字符内,只能是数字、大小写字母_-|* 且在同一个服务商商户号下唯一。


time_expire  选填 string(64)

【支付结束时间】

1、定义:支付结束时间是指用户能够完成该笔订单支付的最后时限,并非订单关闭的时间。超过此时间后,用户将无法对该笔订单进行支付。如需关闭订单,请调用关闭订单API接口。

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秒。

3、注意事项:

  • time_expire 参数仅在用户首次下单时可设置,且不允许后续修改,尝试修改将导致错误。

  • 若用户实际进行支付的时间超过了订单设置的支付结束时间,服务商需使用新的商户订单号下单,生成新的订单供用户进行支付。若未超过支付结束时间,则可使用原参数重新请求下单接口,以获取当前订单最新的prepay_id 进行支付。

  • 支付结束时间不能早于下单时间后1分钟,若设置的支付结束时间早于该时间,系统将自动调整为下单时间后1分钟作为支付结束时间


attach  选填 string(128)

【商户数据包】服务商在创建订单时可传入自定义数据包,该数据对用户不可见,用于存储订单相关的服务商自定义信息,其总长度限制在128字符以内。支付成功后查询订单API支付成功回调通知均会将此字段返回给服务商,并且该字段还会体现在交易账单。


notify_url  必填 string(255)

【商户回调地址】服务商接收支付成功回调通知的地址,需按照notify_url填写注意事项规范填写。


goods_tag  选填 string(32)

【订单优惠标记】代金券在创建时可以配置多个订单优惠标记,标记的内容由创券商户自定义设置。详细参考:创建代金券批次API
如果代金券有配置订单优惠标记,则必须在该参数传任意一个配置的订单优惠标记才能使用券。
如果代金券没有配置订单优惠标记,则可以不传该参数。

示例:
如有两个活动,活动A设置了两个优惠标记:WXG1、WXG2;活动B设置了两个优惠标记:WXG1、WXG3;
下单时优惠标记传WXG2,则订单参与活动A的优惠;
下单时优惠标记传WXG3,则订单参与活动B的优惠;
下单时优惠标记传共同的WXG1,则订单参与活动A、B两个活动的优惠;


settle_info  选填 object

【结算信息】 结算信息

属性

support_fapiao  选填 boolean

【电子发票入口开放标识】 传入true时,支付成功消息和支付详情页将出现开票入口。需要在微信支付服务商平台或微信公众平台开通电子发票功能,传此字段才可生效。 详细参考:电子发票介绍
true:是
false:否


amount  必填 object

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

属性

detail  选填 object

【优惠功能】 优惠功能

属性

scene_info  选填 object

【场景信息】 场景信息

属性

请求示例

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 * App下单
22 */
23public class PartnerAppPrepay {
24  private static String HOST = "https://api.mch.weixin.qq.com";
25  private static String METHOD = "POST";
26  private static String PATH = "/v3/pay/partner/transactions/app";
27
28  public static void main(String[] args) {
29    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
30    PartnerAppPrepay client = new PartnerAppPrepay(
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    PartnerAPIv3CommonPrepayRequest request = new PartnerAPIv3CommonPrepayRequest();
39    request.spAppid = "wx8888888888888888";
40    request.spMchid = "1230000109";
41    request.subAppid = "wxd678efh567hg6999";
42    request.subMchid = "1900000109";
43    request.description = "Image形象店-深圳腾大-QQ公仔";
44    request.outTradeNo = "1217752501201407033233368018";
45    request.timeExpire = "2018-06-08T10:34:56+08:00";
46    request.attach = "自定义数据说明";
47    request.notifyUrl = "https://www.weixin.qq.com/wxpay/pay.php";
48    request.goodsTag = "WXG";
49    request.settleInfo = new PartnerSettleInfo();
50    request.settleInfo.profitSharing = true;
51    request.supportFapiao = false;
52    request.amount = new CommonAmountInfo();
53    request.amount.total = 100L;
54    request.amount.currency = "CNY";
55    request.detail = new CouponInfo();
56    request.detail.costPrice = 1L;
57    request.detail.invoiceId = "wx123";
58    request.detail.goodsDetail = new ArrayList<>();
59    {
60      GoodsDetail item0 = new GoodsDetail();
61      item0.merchantGoodsId = "1246464644";
62      item0.wechatpayGoodsId = "1001";
63      item0.goodsName = "iPhone6s 16G";
64      item0.quantity = 1L;
65      item0.unitPrice = 528800L;
66      request.detail.goodsDetail.add(item0);
67    };
68    request.sceneInfo = new CommonSceneInfo();
69    request.sceneInfo.payerClientIp = "14.23.150.211";
70    request.sceneInfo.deviceId = "013467007045764";
71    request.sceneInfo.storeInfo = new StoreInfo();
72    request.sceneInfo.storeInfo.id = "0001";
73    request.sceneInfo.storeInfo.name = "腾讯大厦分店";
74    request.sceneInfo.storeInfo.areaCode = "440305";
75    request.sceneInfo.storeInfo.address = "广东省深圳市南山区科技中一道10000号";
76    try {
77      PartnerAPIv3AppPrepayResponse response = client.run(request);
78
79      // TODO: 请求成功,继续业务逻辑
80      System.out.println(response);
81    } catch (WXPayUtility.ApiException e) {
82      // TODO: 请求失败,根据状态码执行不同的逻辑
83      e.printStackTrace();
84    }
85  }
86
87  public PartnerAPIv3AppPrepayResponse run(PartnerAPIv3CommonPrepayRequest request) {
88    String uri = PATH;
89    String reqBody = WXPayUtility.toJson(request);
90
91    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
92    reqBuilder.addHeader("Accept", "application/json");
93    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
94    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, reqBody));
95    reqBuilder.addHeader("Content-Type", "application/json");
96    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody);
97    reqBuilder.method(METHOD, requestBody);
98    Request httpRequest = reqBuilder.build();
99
100    // 发送HTTP请求
101    OkHttpClient client = new OkHttpClient.Builder().build();
102    try (Response httpResponse = client.newCall(httpRequest).execute()) {
103      String respBody = WXPayUtility.extractBody(httpResponse);
104      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
105        // 2XX 成功,验证应答签名
106        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
107                                      httpResponse.headers(), respBody);
108
109        // 从HTTP应答报文构建返回数据
110        return WXPayUtility.fromJson(respBody, PartnerAPIv3AppPrepayResponse.class);
111      } else {
112        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
113      }
114    } catch (IOException e) {
115      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
116    }
117  }
118
119  private final String mchid;
120  private final String certificateSerialNo;
121  private final PrivateKey privateKey;
122  private final String wechatPayPublicKeyId;
123  private final PublicKey wechatPayPublicKey;
124
125  public PartnerAppPrepay(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
126    this.mchid = mchid;
127    this.certificateSerialNo = certificateSerialNo;
128    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
129    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
130    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
131  }
132
133  public static class PartnerSettleInfo {
134    @SerializedName("profit_sharing")
135    public Boolean profitSharing;
136  }
137
138  public static class CommonAmountInfo {
139    @SerializedName("total")
140    public Long total;
141
142    @SerializedName("currency")
143    public String currency;
144  }
145
146  public static class CommonSceneInfo {
147    @SerializedName("payer_client_ip")
148    public String payerClientIp;
149
150    @SerializedName("device_id")
151    public String deviceId;
152
153    @SerializedName("store_info")
154    public StoreInfo storeInfo;
155  }
156
157  public static class GoodsDetail {
158    @SerializedName("merchant_goods_id")
159    public String merchantGoodsId;
160
161    @SerializedName("wechatpay_goods_id")
162    public String wechatpayGoodsId;
163
164    @SerializedName("goods_name")
165    public String goodsName;
166
167    @SerializedName("quantity")
168    public Long quantity;
169
170    @SerializedName("unit_price")
171    public Long unitPrice;
172  }
173
174  public static class PartnerAPIv3AppPrepayResponse {
175    @SerializedName("prepay_id")
176    public String prepayId;
177  }
178
179  public static class PartnerAPIv3CommonPrepayRequest {
180    @SerializedName("sp_appid")
181    public String spAppid;
182
183    @SerializedName("sp_mchid")
184    public String spMchid;
185
186    @SerializedName("sub_appid")
187    public String subAppid;
188
189    @SerializedName("sub_mchid")
190    public String subMchid;
191
192    @SerializedName("description")
193    public String description;
194
195    @SerializedName("out_trade_no")
196    public String outTradeNo;
197
198    @SerializedName("time_expire")
199    public String timeExpire;
200
201    @SerializedName("attach")
202    public String attach;
203
204    @SerializedName("notify_url")
205    public String notifyUrl;
206
207    @SerializedName("goods_tag")
208    public String goodsTag;
209
210    @SerializedName("settle_info")
211    public PartnerSettleInfo settleInfo;
212
213    @SerializedName("support_fapiao")
214    public Boolean supportFapiao;
215
216    @SerializedName("amount")
217    public CommonAmountInfo amount;
218
219    @SerializedName("detail")
220    public CouponInfo detail;
221
222    @SerializedName("scene_info")
223    public CommonSceneInfo sceneInfo;
224  }
225
226  public static class CouponInfo {
227    @SerializedName("cost_price")
228    public Long costPrice;
229
230    @SerializedName("invoice_id")
231    public String invoiceId;
232
233    @SerializedName("goods_detail")
234    public List<GoodsDetail> goodsDetail;
235  }
236
237  public static class StoreInfo {
238    @SerializedName("id")
239    public String id;
240
241    @SerializedName("name")
242    public String name;
243
244    @SerializedName("area_code")
245    public String areaCode;
246
247    @SerializedName("address")
248    public String address;
249  }
250}

应答参数

200 OK

prepay_id  必填 string(64)

【预支付交易会话标识】预支付交易会话标识,APP调起支付时需要使用的参数,有效期为2小时,失效后需要重新请求该接口以获取新的prepay_id。

应答示例

200 OK

1{
2  "prepay_id" : "wx201410272009395522657a690389285100"
3}
4

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

APPID_MCHID_NOT_MATCH

AppID和mch_id不匹配

请确认AppID和mch_id是否匹配,查询指引参考:查询商户号绑定的APPID

400

INVALID_REQUEST

无效请求

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

400

MCH_NOT_EXISTS

商户号不存在

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

400

PARAM_ERROR

参数错误

请根据接口返回的错误描述检查参数,参数需按API文档字段填写说明填写

401

SIGN_ERROR

签名错误

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

403

NO_AUTH

商户无权限

请商户前往商户平台申请此接口相关权限,参考:权限申请

403

OUT_TRADE_NO_USED

商户订单号重复

请核实商户订单号是否重复提交

429

FREQUENCY_LIMITED

频率超限

请求频率超限,请降低请求接口频率

500

SYSTEM_ERROR

系统错误

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

 

 

反馈
咨询
目录
置顶