APP下单

更新时间:2025.03.31

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

接口说明

支持商户:【普通商户】

请求方式:【POST】/v3/pay/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 包体参数

appid  必填 string(32)

【商户应用ID】APPID是商户移动应用唯一标识,在开放平台(移动应用)申请。此处需填写与mchid完成绑定的appid,详见:商户模式开发必要参数说明


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两个活动的优惠;


support_fapiao  选填 boolean

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


amount  必填 object

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

属性

detail  选填 object

【优惠功能】 优惠功能

属性

scene_info  选填 object

【场景信息】 场景信息

属性

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

 

 

 

 

 

 

 

应答参数

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

系统错误

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

 

 

反馈
咨询
目录
置顶