1. 接口规则
为了在保证支付安全的前提下,带给商户简单、一致且易用的开发体验,我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
2. 开发准备
2.1. 搭建和配置开发环境
开发者应当依据自身的编程语言来构建并配置相应的开发环境。
2.2. 业务开发配置
2.2.1. 设置支付目录
1.支付授权目录说明:
1)服务商最后请求拉起微信支付收银台的页面地址我们称之为“支付授权目录”,例如:https://www.weixin.com/pay.php的支付授权目录为:https://www.weixin.com/。
2)服务商实际的支付授权目录必须和在微信支付服务商平台设置的一致,否则会报错“当前页面的URL未注册:”
3)服务商模式支付授权目录设置可分为2种方式:
服务商为全体子商户设置支付授权目录
服务商为某一子商户单独设置支付授权目录
2.支付授权目录设置说明:
1)服务商为全体子商户设置支付授权目录
登录微信支付【服务商平台->产品中心->开发配置】,设置后一般5分钟内生效。
登录微信支付【服务商平台->服务商功能—>特约商户管理】,设置后一般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. 设置授权域名
3. 快速接入
3.1. 业务流程图
步骤20 商户在没有接收到微信支付结果通知的情况下需要主动调用查询订单API查询支付结果。
3.2. API接入(含示例代码)
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼,完成与微信支付对接的部分。
3.2.1. 【服务端】JSAPI下单
用户通过商户下发的模板消息或扫描二维码在微信内进入商户网页,当用户选择相关商户购买时,商户系统先调用该接口在微信支付服务后台生成预支付交易单。
1public void CreateOrder() throws Exception{
2
3 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi");
4
5
6 String reqdata = "{"
7 + "\"amount\": {"
8 + "\"total\": 100,"
9 + "\"currency\": \"CNY\""
10 + "},"
11 + "\"mchid\": \"1900006891\","
12 + "\"description\": \"Image形象店-深圳腾大-QQ公仔\","
13 + "\"notify_url\": \"https://www.weixin.qq.com/wxpay/pay.php\","
14 + "\"payer\": {"
15 + "\"openid\": \"o4GgauE1lgaPsLabrYvqhVg7O8yA\"" + "},"
16 + "\"out_trade_no\": \"1217752501201407033233388881\","
17 + "\"goods_tag\": \"WXG\","
18 + "\"appid\": \"wxdace645e0bc2c424\"" + "}";
19 StringEntity entity = new StringEntity(reqdata,"utf-8");
20 entity.setContentType("application/json");
21 httpPost.setEntity(entity);
22 httpPost.setHeader("Accept", "application/json");
23
24
25 CloseableHttpResponse response = httpClient.execute(httpPost);
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 httpClient.close();
39 }
40 }
1try {
2 $resp = $client->request(
3 'POST',
4 'https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi',
5 [
6
7 'json' => [
8 "time_expire" => "2018-06-08T10:34:56+08:00",
9 "amount" => [
10 "total" => 100,
11 "currency" => "CNY",
12 ],
13 "mchid" => "1230000109",
14 "description" => "Image形象店-深圳腾大-QQ公仔",
15 "notify_url" => "https://www.weixin.qq.com/wxpay/pay.php",
16 "payer" => [
17 "openid" => "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
18 ],
19 "out_trade_no" => "1217752501201407033233368018",
20 "goods_tag" => "WXG",
21 "appid" => "wxd678efh567hg6787",
22 "attach" => "自定义数据说明",
23 "detail" => [
24 "invoice_id" => "wx123",
25 "goods_detail" => [
26 [
27 "goods_name" => "iPhoneX 256G",
28 "wechatpay_goods_id" => "1001",
29 "quantity" => 1,
30 "merchant_goods_id" => "商品编码",
31 "unit_price" => 828800,
32 ],
33 [
34 "goods_name" => "iPhoneX 256G",
35 "wechatpay_goods_id" => "1001",
36 "quantity" => 1,
37 "merchant_goods_id" => "商品编码",
38 "unit_price" => 828800,
39 ],
40 ],
41 "cost_price" => 608800,
42 ],
43 "scene_info" => [
44 "store_info" => [
45 "address" => "广东省深圳市南山区科技中一道10000号",
46 "area_code" => "440305",
47 "name" => "腾讯大厦分店",
48 "id" => "0001",
49 ],
50 "device_id" => "013467007045764",
51 "payer_client_ip" => "14.23.150.211",
52 ]
53 ],
54 'headers' => [ 'Accept' => 'application/json' ]
55 ]
56 );
57 $statusCode = $resp->getStatusCode();
58 if ($statusCode == 200) {
59 echo "success,return body = " . $resp->getBody()->getContents()."\n";
60 } else if ($statusCode == 204) {
61 echo "success";
62 }
63 } catch (RequestException $e) {
64
65 echo $e->getMessage()."\n";
66 if ($e->hasResponse()) {
67 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
68 }
69 return;
70 }
out_trade_no: 商户系统内部订单号,只能是数字、大小写字母_-*且在同一个商户号下唯一。
description: 商品描述。
notify_url: 支付回调通知URL,该地址必须为直接可访问的URL,不允许携带查询串。
total: 订单总金额,单位为分。
OpenID: OpenID是微信用户在AppID下的唯一用户标识(AppID不同,则获取到的OpenID就不同),可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID、公众号获取OpenID、App获取OpenID。
3.2.2. 【客户端】JSAPI调起支付
步骤说明: 通过JSAPI下单API成功获取预支付交易会话标识(prepay_id)后,需要通过JSAPI调起支付API来调起微信支付收银台。
| 注意 请确保实际支付时的请求目录与后台配置的目录一致(现在已经支持配置根目录,配置后有一定的生效时间,一般5分钟内生效),否则将无法成功唤起微信支付。配置方式详见支付授权目录。 WeixinJSBridge内置对象在其他浏览器中无效。 JSSDK的wx.chooseWXPay唤起支付,唤起格式内容参考公众号开发指南。 JSSDK的JSSDK使用步骤说明链接地址,内容说明信息。 唤起支付返回的res对象驼峰式是JSSDK返回的格式,而err_msg是WeixinJSBridge返回的格式,如商户使用不同的方式,此处响应的字符大小写、格式需注意。
|
|
1function onBridgeReady() {
2 WeixinJSBridge.invoke('getBrandWCPayRequest', {
3 "appId": "wx2421b1c4370ecxxx",
4 "timeStamp": "1395712654",
5 "nonceStr": "e61463f8efa94090b1f366cccfbbb444",
6 "package": "prepay_id=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 }
17 if (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 }
3.2.3. 【服务端】接收支付结果通知
步骤说明: 当用户完成支付,微信会把相关支付结果将通过异步回调的方式通知商户,商户需要接收处理,并按文档规范返回应答
| 注意 支付结果通知是以POST 方法访问商户设置的通知URL,通知的数据以JSON 格式通过请求主体(BODY)传输。通知的数据包括了加密的支付结果详情。 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名,并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名,以确认请求来自微信,而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。 支付通知HTTP应答码为200或204才会当作正常接收,当回调处理异常时,应答的HTTP状态码应为500,或者4xx。 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。 对后台通知交互时,如果微信收到商户的应答不符合规范或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)。
特别提醒: 商户系统对于开启结果通知的内容一定要做签名验证,并校验通知的信息是否与商户侧的信息一致,防止数据泄露导致出现“假通知”,造成资金损失 |
|
更多参数、响应详情及错误码请参见 支付结果通知支付通知API接口文档。
3.2.4. 【服务端】查询订单
步骤说明: 当商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知时,商户可通过查询订单接口核实订单支付状态。
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/pay/transactions/id/1217752501201407033233368018?mchid=1230000109',
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}
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/pay/transactions/id/1217752501201407033233368018?mchid=1230000109',
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.5. 【服务端】关闭订单
步骤说明: 当商户订单支付失败需要生成新单号重新发起支付,要对原订单号调用关单,避免重复支付;系统下单后,用户支付超时,系统退出不再受理,避免用户继续,请调用关单接口。
1public void CloseOrder() throws Exception {
2
3
4 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/sdkphp12345678920201028112429/close");
5
6 String reqdata ="{\"mchid\": \""+mchId+"\"}";
7
8 StringEntity entity = new StringEntity(reqdata,"utf-8");
9 entity.setContentType("application/json");
10 httpPost.setEntity(entity);
11 httpPost.setHeader("Accept", "application/json");
12
13
14 CloseableHttpResponse response = httpClient.execute(httpPost);
15 try {
16 int statusCode = response.getStatusLine().getStatusCode();
17 if (statusCode == 200) {
18 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
19 } else if (statusCode == 204) {
20 System.out.println("success");
21 } else {
22 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
23 throw new IOException("request failed");
24 }
25 } finally {
26 response.close();
27 }
28 }
1try {
2 $resp = $client->request(
3 'POST',
4 'https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{out_trade_no}/close',
5 [
6
7 'json' => [
8 "mchid " => "1230000109",
9 ],
10 'headers' => [ 'Accept' => 'application/json' ]
11 ]
12 );
13 $statusCode = $resp->getStatusCode();
14 if ($statusCode == 200) {
15 echo "success,return body = " . $resp->getBody()->getContents()."\n";
16 } else if ($statusCode == 204) {
17 echo "success";
18 }
19 } catch (RequestException $e) {
20
21 echo $e->getMessage()."\n";
22 if ($e->hasResponse()) {
23 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
24 }
25 return;
26 }
更多参数、响应详情及错误码请参见 关闭订单接口文档
3.2.6. 【服务端】申请交易账单
步骤说明: 微信支付按天提供交易账单文件,商户可以通过该接口获取账单文件的下载地址。
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}
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&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)后,再通过该接口获取到对应的账单文件,文件内包含交易相关的金额、时间、营销等信息,供商户核对订单、退款、银行到账等情况。
| 注意 账单文件的下载地址的有效时间为30s。 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对,以确认数据的完整性。 该接口响应的信息请求头中不包含微信接口响应的签名值,因此需要跳过验签的流程。 微信在次日9点启动生成前一天的对账单,建议商户10点后再获取。
|
|
1public void DownloadUrl(String download_url) throws Exception{
2 PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));
3
4
5
6 httpClient = WechatPayHttpClientBuilder.create().withMerchant(mchId, mchSerialNo, merchantPrivateKey).withValidator((response) -> true).build();
7
8
9
10 URIBuilder uriBuilder = new URIBuilder(download_url);
11 HttpGet httpGet = new HttpGet(uriBuilder.build());
12 httpGet.addHeader("Accept", "application/json");
13
14
15 CloseableHttpResponse response = httpClient.execute(httpGet);
16 try {
17 int statusCode = response.getStatusLine().getStatusCode();
18 if (statusCode == 200) {
19 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
20 } else if (statusCode == 204) {
21 System.out.println("success");
22 } else {
23 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
24 throw new IOException("request failed");
25 }
26 } finally {
27 response.close();
28 }
29}
1try {
2 $resp = $client->request(
3 'GET',
4 'https://api.mch.weixin.qq.com/v3/billdownload/file?token=xx',
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. 常见问题
Q:获取OpenID接口报“此公众号并没有这些scope的权限,错误码10005”,如下图所示
建议检查一下公众号的功能。比如是不是在订阅号/未认证的公众号里面尝试调用认证服务号的功能。
确认AppID是否认证过期或者AppID填写错误。
请尝试使用snsapi_userinfo的授权登录方式。
Q:JSAPI调起支付接口报“商家暂时没有此类交易权限,请联系商家客服”
请检查你的下单接口是否指定了支付用户的身份,该功能需单独开通指定身份支付权限方可使用。
请确认你使用的商户号是否有jsapi支付的权限,可登录商户平台-产品中心查看。
Q:JSAPI调起支付接口报“当前页面的URL未注册”
Q:获取OpenID接口报“redirect_url域名与后台配置不一致,错误码:10003”
本错误是公众号获取OpenID接口报的错误,可参考文档检查是否符合开发规范:网页授权
检查下单接口传的AppID与获取OpenID接口的AppID是否同一个(需一致)。
检查AppID对应的公众号后台,是否配置的授权域名和获取OpenID的域名一致。授权域名配置路径:【公众平台-> 设置-> 公众号设置-> 功能设置–> 网页授权域名】。
Q:JSAPI调起支付接口报“该商户暂不支持通过外部拉起微信完成支付”
A:JSAPI支付只能从微信浏览器内发起支付请求。