首页成为合作伙伴合作伙伴能力合作伙伴成长文档中心
文档中心
首页接入指引产品中心解决方案文档中心接入微信支付
产品文档通用规则SDK&开发工具更新日志
产品文档
产品文档/
支付产品/
合单支付/
H5支付/
开发指引/

开发指引

更新时间：2024.11.15

1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。

2. 开发准备

2.1. 搭建和配置开发环境

开发者应当依据自身的编程语言来构建并配置相应的开发环境。

2.2. 业务开发配置

合单支付目前支持在微信外H5、App、JSAPI、小程序、Native扫码5个场景使用，下面为你介绍H5场景开发配置。

2.2.1. 开通H5支付权限

开通H5支付权限：前往【微信支付服务商平台—>产品中心—>特约商户授权产品—服务商H5支付—>申请开通】。

开通后让子商户去授权绑定。

设置H5支付域名：登录【微信支付服务商平台—>产品中心—>开发配置—>H5支付】，设置后一般10分钟内生效。

注意

  • 域名必须通过ICP备案

  • 域名填写格式不包含http://或https://。

3. 快速接入

3.1. 业务流程图

业务流程时序图如下。

重点步骤说明：

步骤1：用户在商户侧发起支付请求，商户先通过后台接口合单下单-H5接口创建合单支付订单。

步骤2：商户再根据用户发起支付请求的具体场景通过H5页面调起微信支付收银台，完成支付请求。

步骤3：用户支付成功后，商户可接收到支付结果回调通知。

步骤4：如果商户长时间未收到回调通知，可通过合单查询订单接口主动查询订单支付状态。

3.2. API接入（含示例代码）

文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。

注意

  • 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。

  • 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1. 【服务端】合单下单-H5

步骤说明： 用户在商户侧选择商品下单购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单，然后使用我们提供的客户端方法（下文介绍）调起微信支付收银台，即可完成支付。

JAVA示例代码：

1public void CombineJsapiPrepay() throws Exception{
2    //请求URL
3    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/h5");
4    
5    // 请求body参数
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) { //处理成功，无返回Body
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/h5', //请求URL
5        [
6            // JSON请求体
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) { //处理成功，无返回Body
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。

更多参数、响应详情及错误码请参见合单下单-H5。

3.2.2. 【客户端】微信外H5浏览器拉起微信支付中间页

步骤说明： 通过H5下单API成功获取H5下单返回的支付中间页（h5_url）后，用户需要通过微信外部的浏览器调起微信支付收银台

注意

  • h5_url为拉起微信支付收银台的中间页面，可通过访问该URL来拉起微信客户端，完成支付，h5_url的有效期为5分钟。

  • 微信支付收银台中间页会进行H5权限的校验，安全性检查。

  • 正常流程用户支付完成后会返回至发起支付的页面，如需返回至指定页面，则可以在h5_url后拼接上redirect_url参数，来指定回调页面。您希望用户支付完成后跳转至https://www.wechatpay.com.cn，则拼接后的地址为h5_url= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn。

  • 需对redirect_url进行urlencode处理

  • 由于设置redirect_url后,回跳指定页面的操作可能发生在：

    1. 微信支付中间页调起微信收银台后超过5秒。

    2. 用户点击“取消支付”或支付完成后点“完成”按钮。因此无法保证页面回跳时，支付流程已结束，所以商户设置的redirect_url地址不能自动执行查单操作，应让用户去点击按钮触发查单操作，回跳页面展示效果可参考下图。

更多参数、响应详情及错误码请参见H5调起支付接口文档。

3.2.3. 【服务端】接收支付结果通知

步骤说明： 当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答。

注意

  • 支付结果通知的地址需要在请求合单H5下单API时传入notify_url参数中。

  • 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。

  • 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。

  • 支付结果通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。

  • 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。

  • 后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信会判定本次通知失败，重新发送通知，直到成功为止，但微信不保证通知最终一定能成功。

特别提醒：

  • 商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。

  • 当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

更多参数、响应详情及错误码请参见支付结果通知接口文档。

3.2.4. 【服务端】合单查询订单

步骤说明： 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付结果通知时商户可通过查询订单接口核实订单支付状态。

JAVA示例代码：

1public void QueryOrder() throws Exception {
2  
3  //请求URL
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', //请求URL
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) { //处理成功，无返回Body
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. 【服务端】合单关闭订单

步骤说明： 当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。

示例代码：

JAVA示例代码：

1public void CombineCloseOrder() throws Exception{
2  
3  //请求URL
4  HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close");
5  // 请求body参数
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) { //处理成功，无返回Body
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', //请求URL
5        [
6            // JSON请求体
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) { //处理成功，无返回Body
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}

注意

  • 订单生成后不能马上调用关单接口，最短调用时间间隔为5分钟。

  • 已支付成功的订单不能关闭。

更多参数、响应详情及错误码请参见合单关单接口文档。

3.2.6. 【服务端】申请交易账单

步骤说明： 微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。

示例代码：

JAVA示例代码：

1public void TradeBill() throws Exception {
2  
3  //请求URL
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', //请求URL
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) { //处理成功，无返回Body
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.7. 【服务端】下载账单

步骤说明： 通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况。

JAVA示例代码：

1public void TradeBill() throws Exception {
2  
3  //请求URL
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', //请求URL
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) { //处理成功，无返回Body
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}

注意

  • 账单文件的下载地址的有效时间为30s。

  • 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性。

更多参数、响应详情及错误码请参见下载账单接口文档。

4. 常见问题

问: 获取OpenID接口报“此公众号并没有这些scope的权限，错误码10005”，如下图所示。

答: 请按以下步骤进行排查：

  1. 建议检查一下公众号的功能。比如是不是在订阅号/未认证的公众号里面尝试调用认证服务号的功能。

  2. 确认AppID是否认证过期或者AppID填写错误。

  3. 请尝试使用snsapi_userinfo的授权登录方式。

问：获取OpenID接口报“redirect_url域名与后台配置不一致，错误码：10003”。

答：请按以下步骤进行排查：

  1. 本错误是公众号获取OpenID接口报的错误，可参考文档检查是否符合开发规范：网页授权

  2. 检查下单接口传的AppID与获取OpenID接口的AppID是否同一个（需一致）。

  3. 检查AppID对应的公众号后台，是否配置的授权域名和获取OpenID的域名一致。授权域名配置路径：【公众平台-> 设置-> 公众号设置-> 功能设置–> 网页授权域名】。

 

更多支持
开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服
更多技术问题
技术咨询
1. 接口规则
2. 开发准备
2.1. 搭建和配置开发环境
2.2. 业务开发配置
2.2.1. 开通H5支付权限
3. 快速接入
3.1. 业务流程图
3.2. API接入（含示例代码）
3.2.1. 【服务端】合单下单-H5
3.2.2. 【客户端】微信外H5浏览器拉起微信支付中间页
3.2.3. 【服务端】接收支付结果通知
3.2.4. 【服务端】合单查询订单
3.2.5. 【服务端】合单关闭订单
3.2.6. 【服务端】申请交易账单
3.2.7. 【服务端】下载账单
4. 常见问题
反馈
咨询
目录
置顶
Powered By Tencent & Tenpay Copyright 2005-2024 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2024 Tenpay All Rights Reserved.