1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
2. 开发准备
2.1. 搭建和配置开发环境
开发者应当依据自身的编程语言来构建并配置相应的开发环境。
2.2. 业务开发配置
合单支付目前支持在微信外H5、App、JSAPI、小程序、Native扫码5个场景使用，下面为你介绍JSAPI场景开发配置。
2.2.1. 设置支付目录
一、支付授权目录说明：
商户最后请求拉起微信支付收银台的页面地址我们称之为“支付目录”，例如：https://www.weixin.com/pay.php。
商户实际的支付目录必须和在微信支付商户平台设置的一致，否则会报错“当前页面的URL未注册：”
二、支付授权目录设置说明：
登录【微信支付服务商平台> 产品中心 > 开发配置】，设置后一般5分钟内生效。（配置页见下图）
3.支付授权目录校验规则说明：
如果支付授权目录设置为顶级域名（例如：https://www.weixin.com/ ），那么只校验顶级域名，不校验后缀；
如果支付授权目录设置为多级目录，就会进行全匹配，例如设置支付授权目录为 https://www.weixin.com/abc/123/，则实际请求页面目录不能为https://www.weixin.com/abc/，也不能为https://www.weixin.com/abc/123/pay/，必须为https://www.weixin.com/abc/123/。
2.2.2. 设置授权域名
授权域名说明：开发JSAPI支付时，在JSAPI下单接口中要求必传用户OpenID，而获取OpenID则需要您在公众平台设置获取OpenID的域名，只有被设置过的域名才是一个有效的获取OpenID的域名，否则将获取失败。具体配置页见下图。
授权域名设置说明：登录【微信公众平台->公众号设置】
3. 快速接入
3.1. 业务流程图
业务流程时序图如下。
重点步骤说明：
步骤2：商户再根据用户发起支付请求的具体场景通过合单下单-JSAPI页面调起微信支付收银台，完成支付请求。
步骤4：如果商户长时间未收到回调通知，可通过合单查询订单接口主动查询订单支付状态。
3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。
3.2.1. 【服务端】JSAPI下单
步骤说明：用户在商户侧选择商品下单购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单，然后使用我们提供的客户端方法（下文介绍）调起微信支付收银台，即可完成支付。
示例代码：
JAVA示例代码：
1public void CombineJsapiPrepay() throws Exception{
2
3 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/jsapi");
4
5
6 String reqdata = "{"
7 + "\"combine_out_trade_no\":\"1217752501201407033233368018\","
8 + "\"combine_mchid\":\"1230000109\","
9 + "\"combine_appid\":\"wxd678efh567hg6787\","
10 + "\"scene_info\": {"
11 + "\"device_id\":\"POS1:1\","
12 + "\"payer_client_ip\":\"14.17.22.32\""
13 + "},"
14 + "\"sub_orders\": ["
15 + "{"
16 + "\"mchid\":\"1230000109\","
17 + "\"attach\":\"深圳分店\","
18 + "\"amount\": {"
19 + "\"total_amount\":10,"
20 + "\"currency\":\"CNY\""
21 + "},"
22 + "\"out_trade_no\":\"20150806125346\","
23 + "\"sub_mchid\":\"1900000109\","
24 + "\"description\":\"腾讯充值中心-QQ会员充值\""
25 + "}"
26 + "],"
27 + "\"combine_payer_info\": {"
28 + "\"openid\":\"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o\""
29 + "},"
30 + "\"time_start\":\"2018-06-08T10:34:56+08:00\","
31 + "\"time_expire\":\"2018-06-08T10:34:56+08:00\","
32 + "\"notify_url\":\"https://yourapp.com/notify\""
33 + "}";
34 StringEntity entity = new StringEntity(reqdata,"utf-8");
35 entity.setContentType("application/json");
36 httpPost.setEntity(entity);
37 httpPost.setHeader("Accept", "application/json");
38
39
40 CloseableHttpResponse response = httpClient.execute(httpPost);
41
42 try {
43 int statusCode = response.getStatusLine().getStatusCode();
44 if (statusCode == 200) {
45 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
46 } else if (statusCode == 204) {
47 System.out.println("success");
48 } else {
49 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
50 throw new IOException("request failed");
51 }
52 } finally {
53 response.close();
54 }
55}PHP示例代码
1try {
2 $resp = $client->request(
3 'POST',
4 'https://api.mch.weixin.qq.com/v3/combine-transactions/jsapi',
5 [
6
7 'json' => [
8 "combine_out_trade_no" => "1217752501201407033233368018",
9 "combine_mchid" => "1230000109",
10 "combine_appid" => "wxd678efh567hg6787",
11 "scene_info" => [
12 "device_id" => "POS1:1",
13 "payer_client_ip" => "14.17.22.32",
14 ],
15 "sub_orders" => [
16 [
17 "mchid" => "1230000109",
18 "attach" => "深圳分店",
19 "amount" => [
20 "total_amount" => 10,
21 "currency" => "CNY",
22 ],
23 "out_trade_no" => "20150806125346",
24 "sub_mchid" => "1900000109",
25 "description" => "腾讯充值中心-QQ会员充值",
26 ],
27 ],
28 "combine_payer_info" => [
29 "openid" => "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
30 ],
31 "time_start" => "2018-06-08T10:34:56+08:00",
32 "time_expire" => "2018-06-08T10:34:56+08:00",
33 "notify_url" => "https://yourapp.com/notify",
34 ],
35 'headers' => [ 'Accept' => 'application/json' ]
36 ]
37 );
38 $statusCode = $resp->getStatusCode();
39 if ($statusCode == 200) {
40 echo "success,return body = " . $resp->getBody()->getContents()."\n";
41 } else if ($statusCode == 204) {
42 echo "success";
43 }
44} catch (RequestException $e) {
45
46 echo $e->getMessage()."\n";
47 if ($e->hasResponse()) {
48 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
49 }
50 return;
51}重要入参说明：
out_trade_no： 商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一。
description： 商品描述。
notify_url： 支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串。
total： 订单总金额，单位为分。
OpenID： OpenID是微信用户在AppID下的唯一用户标识（AppID不同，则获取到的OpenID就不同），可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID、公众号获取OpenID、App获取OpenID。
更多参数、响应详情及错误码请参见合单下单-JSAPI。
3.2.2. 【客户端】JSAPI调起支付
步骤说明： 通过JSAPI下单API成功获取预支付交易会话标识（prepay_id）后，需要通过JSAPI调起支付API来调起微信支付收银台。
示例代码：
1function onBridgeReady() {
2 WeixinJSBridge.invoke('getBrandWCPayRequest', {
3 "appId": "wx2421b1c4370ecxxx",
4 "timeStamp": "1395712654",
5 "nonceStr": "e61463f8efa94090b1f366cccfbbb444",
6 "package": "prepay_id=up_wx21201855730335ac86f8c43d1889123400",
7 "signType": "RSA",
8 "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg=="
9 },
10 function(res) {
11 if (res.err_msg == "get_brand_wcpay_request:ok") {
12
13
14 }
15 });
16}
17if (typeof WeixinJSBridge == "undefined") {
18 if (document.addEventListener) {
19 document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
20 } else if (document.attachEvent) {
21 document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
22 document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
23 }
24} else {
25 onBridgeReady();
26}重要入参说明：
paySign生成规则、响应详情及错误码请参见JSAPI调起支付接口文档。
3.2.3. 【服务端】接收支付结果通知
步骤说明： 当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答
| 注意 支付结果通知的地址需要在请求合单JSAPI下单API时传入notify_url参数中。 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。 支付结果通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信会判定本次通知失败，重新发送通知，直到成功为止，但微信不保证通知最终一定能成功。
商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。 当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
|
|
更多参数、响应详情及错误码请参见支付结果通知API接口文档。
3.2.4. 【服务端】合单查询订单
步骤说明： 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知时，商户可通过查询订单接口核实订单支付状态。
示例代码：
JAVA示例代码：
1public void QueryOrder() throws Exception {
2
3
4 URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/P11093730578574");
5 uriBuilder.setParameter("mchid", mchId);
6
7
8 HttpGet httpGet = new HttpGet(uriBuilder.build());
9 httpGet.addHeader("Accept", "application/json");
10 CloseableHttpResponse response = httpClient.execute(httpGet);
11
12 try {
13 int statusCode = response.getStatusLine().getStatusCode();
14 if (statusCode == 200) {
15 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
16 } else if (statusCode == 204) {
17 System.out.println("success");
18 } else {
19 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
20 throw new IOException("request failed");
21 }
22 } finally {
23 response.close();
24 }
25}PHP示例代码：
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/P11093730578574',
5 [
6 'headers' => [ 'Accept' => 'application/json']
7 ]
8 );
9 $statusCode = $resp->getStatusCode();
10 if ($statusCode == 200) {
11 echo "success,return body = " . $resp->getBody()->getContents()."\n";
12 } else if ($statusCode == 204) {
13 echo "success";
14 }
15} catch (RequestException $e) {
16
17 echo $e->getMessage()."\n";
18 if ($e->hasResponse()) {
19 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20 }
21 return;
22}更多参数、响应详情及错误码请参见查询订单API接口文档。
3.2.5. 【服务端】合单关闭订单
步骤说明： 当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。
JAVA示例代码
1public void CombineCloseOrder() throws Exception{
2
3
4 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close");
5
6 String reqdata = "{"
7 + "\"combine_appid \":\"wxd678efh567hg6787\","
8 + "\"combine_out_trade_no\":\"P20150806125346\","
9 + "\"sub_orders\": ["
10 + "{"
11 + "\"mchid\":\"1900000109\","
12 + "\"out_trade_no\":\"20150806125346\","
13 + "\"sub_mchid\":\"1230000109\","
14 + "\"description\":\"腾讯充值中心-QQ会员充值\""
15 + "}"
16 + "]"
17 + "}";
18 StringEntity entity = new StringEntity(reqdata,"utf-8");
19 entity.setContentType("application/json");
20 httpPost.setEntity(entity);
21 httpPost.setHeader("Accept", "application/json");
22
23
24 CloseableHttpResponse response = httpClient.execute(httpPost);
25
26 try {
27 int statusCode = response.getStatusLine().getStatusCode();
28 if (statusCode == 200) {
29 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
30 } else if (statusCode == 204) {
31 System.out.println("success");
32 } else {
33 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
34 throw new IOException("request failed");
35 }
36 } finally {
37 response.close();
38 }
39}PHP示例：
1try {
2 $resp = $client->request(
3 'POST',
4 'https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close',
5 [
6
7 'json' => [
8 "combine_appid " => "wxd678efh567hg6787",
9 "combine_out_trade_no" => "P20150806125346",
10 "sub_orders" => [
11 [
12 "mchid" => "1900000109",
13 "out_trade_no" => "20150806125346",
14 "sub_mchid" => "1230000109",
15 "description" => "腾讯充值中心-QQ会员充值",
16 ],
17 ]
18 ],
19 'headers' => [ 'Accept' => 'application/json' ]
20 ]
21 );
22 $statusCode = $resp->getStatusCode();
23 if ($statusCode == 200) {
24 echo "success,return body = " . $resp->getBody()->getContents()."\n";
25 } else if ($statusCode == 204) {
26 echo "success";
27 }
28} catch (RequestException $e) {
29
30 echo $e->getMessage()."\n";
31 if ($e->hasResponse()) {
32 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
33 }
34 return;
35}更多参数、响应详情及错误码请参见合单关单API接口文档。
3.2.6. 【服务端】申请交易账单
步骤说明： 微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。
JAVA示例代码：
1public void TradeBill() throws Exception {
2
3
4 URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/bill/tradebill");
5 uriBuilder.setParameter("bill_date", "2020-11-09");
6 uriBuilder.setParameter("bill_type", "ALL");
7
8
9 HttpGet httpGet = new HttpGet(uriBuilder.build());
10 httpGet.addHeader("Accept", "application/json");
11 CloseableHttpResponse response = httpClient.execute(httpGet);
12
13 try {
14 int statusCode = response.getStatusLine().getStatusCode();
15 if (statusCode == 200) {
16 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
17 } else if (statusCode == 204) {
18 System.out.println("success");
19 } else {
20 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
21 throw new IOException("request failed");
22 }
23 } finally {
24 response.close();
25 }
26}PHP示例代码：
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&sub_mchid=1900000001&bill_type=ALL',
5 [
6 'headers' => [ 'Accept' => 'application/json']
7 ]
8 );
9 $statusCode = $resp->getStatusCode();
10 if ($statusCode == 200) {
11 echo "success,return body = " . $resp->getBody()->getContents()."\n";
12 } else if ($statusCode == 204) {
13 echo "success";
14 }
15} catch (RequestException $e) {
16
17 echo $e->getMessage()."\n";
18 if ($e->hasResponse()) {
19 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20 }
21 return;
22}更多参数、响应详情及错误码请参见申请交易账单接口文档。
3.2.7. 【服务端】下载账单
步骤说明： 过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况。
示例代码：
JAVA示例代码：
1public void TradeBill() throws Exception {
2
3
4 URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/bill/tradebill");
5 uriBuilder.setParameter("bill_date", "2020-11-09");
6 uriBuilder.setParameter("bill_type", "ALL");
7
8
9 HttpGet httpGet = new HttpGet(uriBuilder.build());
10 httpGet.addHeader("Accept", "application/json");
11 CloseableHttpResponse response = httpClient.execute(httpGet);
12
13 try {
14 int statusCode = response.getStatusLine().getStatusCode();
15 if (statusCode == 200) {
16 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
17 } else if (statusCode == 204) {
18 System.out.println("success");
19 } else {
20 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
21 throw new IOException("request failed");
22 }
23 } finally {
24 response.close();
25 }
26}PHP示例代码：
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&sub_mchid=1900000001&bill_type=ALL',
5 [
6 'headers' => [ 'Accept' => 'application/json']
7 ]
8 );
9 $statusCode = $resp->getStatusCode();
10 if ($statusCode == 200) {
11 echo "success,return body = " . $resp->getBody()->getContents()."\n";
12 } else if ($statusCode == 204) {
13 echo "success";
14 }
15} catch (RequestException $e) {
16
17 echo $e->getMessage()."\n";
18 if ($e->hasResponse()) {
19 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20 }
21 return;
22}更多参数、响应详情及错误码请参见下载账单接口文档。
4. 常见问题
问：获取OpenID接口报“此公众号并没有这些scope的权限，错误码10005”，如下图所示
答：请按以下步骤进行排查：
建议检查一下公众号的功能。比如是不是在订阅号/未认证的公众号里面尝试调用认证服务号的功能。
确认AppID是否认证过期或者AppID填写错误。
请尝试使用snsapi_userinfo的授权登录方式。
问：JSAPI调起支付接口报“商家暂时没有此类交易权限，请联系商家客服”
答：请按以下步骤进行排查：
请检查你的下单接口是否指定了支付用户的身份，该功能需单独开通指定身份支付权限方可使用。
请确认你使用的商户号是否有jsapi支付的权限，可登录商户平台-产品中心查看。
问：JSAPI调起支付接口报“当前页面的URL未注册”
答：请检查下单接口中使用的商户号是否在服务商平台配置了对应的支付目录可参考“2.2.3.1.设置支付目录”章节说明。
问：获取OpenID接口报“redirect_url域名与后台配置不一致，错误码：10003”
答：请按以下步骤进行排查：
本错误是公众号获取OpenID接口报的错误，可参考文档检查是否符合开发规范：网页授权
检查下单接口传的AppID与获取OpenID接口的AppID是否同一个（需一致）。
检查AppID对应的公众号后台，是否配置的授权域名和获取OpenID的域名一致。授权域名配置路径：【公众平台-> 设置-> 公众号设置-> 功能设置–> 网页授权域名】。
问：JSAPI调起支付接口报“该商户暂不支持通过外部拉起微信完成支付”
答：JSAPI支付只能从微信浏览器内发起支付请求。
