开发指引

更新时间：2024.10.22

1. 开发前配置

开发前，开发者需要完成配置开发参数步骤：

1.1 配置开发参数

参数名	用途和申请说明
mchid	在微信侧入驻的平台商户，在服务商平台申请。
appid	平台商户应用载体ID，可以是公众号/小程序/移动应用，在开放平台(移动应用)和公众平台(公众号/小程序)申请，平台商户需要绑定appid才能在该载体中使用微信支付，详细请参考服务商商户号与AppID账号关联管理。
APIV3密钥	平台商户接收APIv3回调密文后需使用该密钥解密，获取平台证书公钥也需要使用该密钥解密，设置方式参考APIv3密钥设置方法。
商户API证书	平台商户调用APIv3接口请求时需要使用该证书私钥生成请求签名，v2部分涉及资金操作接口(如退款/撤销/企业付款等)请求也需要携带该证书，获取方式参考商户API证书获取方法及功能介绍
微信支付平台证书	平台商户调用APIv3接口返回时需要使用该证书公钥进行验签，v3部分含有敏感信息参数接口也需要使用平台证书公钥加密，获取方式参考如何下载平台证书。

2. 详细开发指引

2.1 个人收款方授权开发指引

2.1.1 业务流程图

关键步骤说明
步骤1.2：在展示签约入口前，需查询个人收款方授权结果，若已签约，则无需展示入口; 若未签约需返回签名相关信息，用于展示签约页面。签名必须使用appid, mchid, openid作为参数，签名方法参考：小程序调起支付API。
参与签名字段及格式：

1小程序appId
2时间戳
3随机字符串
4mchid
5openid

步骤1.4： 展示签约页面需要带签名。
步骤1.7：签约结果回调返回的业务数据与查询个人收款方授权结果 结果返回一致

提示：

虽然签约结果回调返回的业务数据与查询个人收款方授权结果 接口返回一致，但不能完全信任客户端结果，重要流程需要后台查询商户 API确认，以免后续交易流程校验失败。

2.1.2 API接入（含示例代码）

2.1.2.1【服务端】查询个人收款方授权结果

1# 示例请求 URL待定
2curl https://api.mch.weixin.qq.com/v3/ecommerce/individual-contracts/oUpF8uMuAJOM2pxb1Q9zNjWeS6o?appid=wxd678efh567h23787&permission_type=INDIVIDUAL_PAYEE -H 'Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900009191",nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",signature="uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==",timestamp="1554208460",serial_no="1DDE55AD98ED71D6EDD4A4A16996DE7B47773A8C"'

请求参数说明(需用商户证书签名)：

appid：string(32) 签约和付款的微信小程序AppID。支付过程中将基于该ID验证对应的用户标识（OpenID）。
permission_type: string(32) 签约的权限，目前只支持个人收款权限，转入INDIVIDUAL_PAYEE。
openid： string[1,128] 个人收款方在平台AppID下的唯一标识。小程序获取OpenID、公众号获取OpenID、App获取OpenID。

响应参数说明

code: string 错误码
message: string[10,128] 错误描述
data
- individual_auth_id： string(32) 授权id（参与方关系：个人收款方受理授权），表示一个【微信支付用户账号id】与一个【商户】的授权关系。
- auth_state： string[10,128] 授权结果状态
  - AUTHORIZED:已授权,
  - UNAUTHORIZED:未授权
- operation_time: string 操作时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。

2.1.2.2【客户端】请求展示签约页面

步骤说明：请求展示签约页面,。用户签约完整后，返回签约授权ID。
支持的调用端：小程序
接入指引：

安装 NPM包
在本地开发环境，使用 NPM 安装依赖包（暂未发布，后续更新）：
```
1npm install -S @tenpay/wechatpay-miniprogram-individual-contracts
```

调用请求用户确认收款接口
通过 WechatPayPlatSolutionEcommerce.requestSign 方法，拉起签约页面。
示例代码（请求与回调参数说明见下文）：

1import  WeChatPayIndividualContracts  from '@tenpay/wechatpay-miniprogram-individual-contracts';
2
3WeChatPayIndividualContracts.requestSign({
4 mchid: '1900000000',
5 appid: 'wx8888888888888888',
6 timeStamp: '1414561699',
7 nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
8 package: 'openid=wxidd678efh567hg6787&permissionType=INDIVIDUAL_PAYEE',
9 signType: 'RSA',
10 signature: 'oR9d8PuhnIc+YZ8cBHFCwfgp...',
11 success: function (res) {
12   // 已确认收款, 结算结果以服务端回调为准
13 },
14 fail: function (err) {
15   // 确认收款失败, 详见: `err.code` `err.message`
16 },
17 complete: function () {
18   // 无论成功/失败均会回调
19 },
20});

paySign生成规则、响应详情请参见个人收款签约小程序 API接口文档。档。

2.2. 交易开发指引

2.2.1. 业务流程图

步骤4：商户通过个人收款交易下单-小程序API 创建支付订单。注意下单传入的参数appid，必须为用户选购并且付款的微信小程序AppID。

步骤7：生成带签名支付信息，商户必须使用下单时的appid，作为签名参数。签名方法参考：小程序调起支付API

步骤9：商户小程序内小程序SDK调起微信支付，详见小程序API文档。小程序SDK会自动将当前用户使用的小程序AppID传给微信支付，微信支付将会校验当前小程序AppID是否与下单、签名所使用的一致。

步骤16：用户支付成功后，商户可接收到微信支付支付结果通知个人收款交易支付通知API。

步骤21：商户在没有接收到微信支付结果通知的情况下需要主动调用个人收款交易通过微信支付订单号查单API 或个人收款交易通过商户订单号查单API 查询支付结果。

提示

建议为确保收款成功避免资金损失，无论是否收到支付成功通知都请主动查单。

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

本章节展示了如何使用微信支付服务端 SDK 快速接入平台收付通-个人收款（小程序支付）产品，完成与微信支付对接的部分。

如果开发者使用过PostmanAPI的调试，建议在正式开发之前，使用 Postman签名脚本进行接口体验。

提示

文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

2.2.2.1. 【服务端】小程序交易下单

步骤说明：用户通过商户小程序进入商户网页，当用户选择相关商品购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单。

java示例代码:

1public void CreateOrder() throws Exception{
2//请求URL
3HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/miniprogram");
4
5// 请求body参数
6String reqdata = "{"
7        + "\"combine_appid\": \"wxd678efh567hg6787\","
8        + "\"combine_mchid\": \"1230000109\","
9        + "\"combine_out_trade_no\": \"1217752501201407033233368018\","
10        + "\"combine_payer_info\": {"
11        + "\"openid\": \"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o\""
12        + "},"
13        + "\"scene_info\": {"
14        + "\"device_id\": \"POS1:1\","
15        + "\"payer_client_ip\": \"14.17.22.32\""
16        + "},"
17        + "\"sub_orders\": ["
18        + "{"
19        + "\"mchid\": \"1230000109\","
20        + "\"individual_auth_id\": \"1900000109\","
21        + "\"out_trade_no\": \"20150806125346\","
22        + "\"amount\": {"
23        + "\"total_amount\": 10,"
24        + "\"currency\": \"CNY\""
25        + "},"
26        + "\"attach\": \"深圳分店\","
27        + "\"detail\": \"买单费用\","
28        + "\"description\": \"腾讯充值中心-QQ会员充值\","
29  + "\"transfer_scene"\": "\"SECOND_HAND_ECOMMERCE"\",
30        + "\"settle_info\": {"
31        + "\"profit_sharing\": false,"
32        + "\"subsidy_amount\": 0"
33        + "},"
34        + "\"goods_tag\": \"WXG\""
35        + "}"
36        + "],"
37        + "\"time_start\": \"2018-06-08T10:34:56+08:00\","
38        + "\"time_expire\": \"2018-06-08T10:34:56+08:00\","
39        + "\"notify_url\": \"https://yourapp.com/notify\""
40  + "}";
41StringEntity entity = new StringEntity(reqdata,"utf-8");
42entity.setContentType("application/json");
43httpPost.setEntity(entity);
44httpPost.setHeader("Accept", "application/json");
45
46//完成签名并执行请求
47CloseableHttpResponse response = httpClient.execute(httpPost);
48try {
49    int statusCode = response.getStatusLine().getStatusCode();
50    if (statusCode == 200) {
51        System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
52    } else if (statusCode == 204) {
53        System.out.println("success");
54    } else {
55        System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
56        throw new IOException("request failed");
57    }
58} finally {
59    response.close();
60}
61}
62

PHP示例代码：

1try {
2    $resp = $client->request(
3     'POST',
4     'https://api.mch.weixin.qq.com/v3/pay/transactions/miniprogram', //请求URL
5     [
6         // JSON请求体
7         'json' => [
8             "combine_appid" => "wxd678efh567hg6787",
9             "combine_mchid" => "1230000109",
10             "combine_out_trade_no" => "1217752501201407033233368018",
11             "combine_payer_info" => [
12                 "openid" => "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
13             ],
14             "scene_info" => [
15                 "device_id" => "POS1:1",
16                 "payer_client_ip" => "14.17.22.32"
17             ],
18             "sub_orders" => [
19                [
20                    "mchid" => "1230000109",
21                    "individual_auth_id" => "1900000109",
22                    "out_trade_no" => "20150806125346",
23                    "amount" => [
24                        "total_amount" => 10,
25                        "currency" => "CNY"
26                    ],
27                    "attach" => "深圳分店",
28                    "detail" => "买单费用",
29                    "description" => "腾讯充值中心-QQ会员充值",
30                    "settle_info" => [
31                      "profit_sharing" => false,
32                        "subsidy_amount" => 0
33                    ],
34                    "goods_tag" => "WXG"
35                ]
36             ],
37             "time_start" => "2018-06-08T10:34:56+08:00",
38             "time_expire" => "2018-06-08T10:34:56+08:00",
39             "notify_url" => "https://yourapp.com/notify"
40           ],
41         'headers' => [ 'Accept' => 'application/json' ]
42     ]
43 );
44    $statusCode = $resp->getStatusCode();
45    if ($statusCode == 200) { //处理成功
46        echo "success,return body = " . $resp->getBody()->getContents()."\n";
47    } else if ($statusCode == 204) { //处理成功，无返回Body
48        echo "success";
49    }
50} catch (RequestException $e) {
51    // 进行错误处理
52    echo $e->getMessage()."\n";
53    if ($e->hasResponse()) {
54        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
55    }
56    return;
57}
58

重要入参说明：

combine_appid：发起交易的平台商户应用ID。
combine_mchid：发起交易的平台商户号。
combine_out_trade_no：商户系统内部对交易单定义的订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户号下唯一。
openid：使用平台商户应用AppID获取的对应用户OpenID，是微信用户在AppID下的唯一用户标识（AppID不同，则获取到的OpenID就不同），可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID、公众号获取OpenID、App获取OpenID。
notify_url：支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串。
trade_scenario：交易场景，可选取值有 RECOMMERCE（二手电商）、TIP（打赏）。
sub_orders：商品单列表，最多支持10条。
- mchid：商品单发起方商户号，即平台商户号，与发起方AppID有绑定关系。
- individual_auth_id：标识一个微信用户在该平台用于个人收款的微信支付账户，平台邀请微信用户完成个人收款授权后获得此ID，详见查询个人收款方授权结果。
- out_trade_no：商户系统内部对商品单定义的订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户号下唯一。
- total_amount：商品单金额，单位为分。
- description：对商品信息的描述，将展示在用户的支付密码确认页、支付凭证、用户账单详情中。

更多参数、响应详情及错误码请参见个人收款交易下单-小程序API 接口文档。

2.2.2.2. 【客户端】小程序调起支付API

步骤说明：通过小程序下单成功获取预支付交易会话标识（prepay_id）后，需要通过小程序调起支付API来调起微信支付收银台。

提示

此API需要将请求参数进行签名（参与签名的参数为：AppID、timeStamp、nonceStr、package，参数区分大小写）。
AppID必须为最后拉起收银台的小程序AppID。

示例代码：

1wx.requestPayment(
2{
3"timeStamp": "1414561699",
4"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
5"package": "prepay_id=wx201410272009395522657a690389285100",
6"signType": "RSA",
7"paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==",
8// suceess仅表示接口调用成功，不表示支付成功
9"success":function(res){
10    // 请求商户后台查单确定订单状态、其他处理逻辑...
11},
12"fail":function(res){
13    // 其他处理逻辑...
14},
15"complete":function(res){
16    // 请求商户后台查单确定订单状态、其他处理逻辑...
17}
18})

重要入参说明：

package：小程序下单接口返回的prepay_id参数值，提交格式如：prepay_id=*。
signType：该接口V3版本仅支持RSA。
paySign：签名。
nonceStr：自定义随机数。

paySign生成规则、响应详情请参见小程序调起支付API接口文档。

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

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

提示

支付结果通知的地址需要在请求App下单API时传入notify_url参数中。
支付结果通知是以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）

特别提醒：

商户系统对于开启结果通知的内容一定要做签名验证，并校验通知的信息是否与商户侧的信息一致，防止数据泄露导致出现“假通知”，造成资金损失。
当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

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

2.2.2.4. 【服务端】查询订单

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

提示

查询订单可通过微信支付订单号和商户订单号两种方式查询。
推荐使用微信支付订单号查询，比通过商户订单号查询快10~20ms。

java示例代码(通过微信订单号查询)：

1
2public void QueryOrder() throws Exception {
3   
4  //请求URL
5  URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/combine-transactions/id/1217752501201407033233368018");
6  uriBuilder.setParameter("mchid", mchId);
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} 
27

PHP示例代码(通过微信订单号查询)：

1
2try {
3    $resp = $client->request(
4        'GET',
5        'https://api.mch.weixin.qq.com/v3/combine-transactions/id/1217752501201407033233368018', //请求URL
6        [
7            'headers' => [ 'Accept' => 'application/json']
8        ]
9    );
10    $statusCode = $resp->getStatusCode();
11    if ($statusCode == 200) { //处理成功
12        echo "success,return body = " . $resp->getBody()->getContents()."\n";
13    } else if ($statusCode == 204) { //处理成功，无返回Body
14        echo "success";
15    }
16} catch (RequestException $e) {
17    // 进行错误处理
18    echo $e->getMessage()."\n";
19    if ($e->hasResponse()) {
20        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
21    }
22    return;
23}
24

更多参数、响应详情及错误码请参见个人收款交易通过微信支付订单号查单API 和个人收款交易通过商户订单号查单API 接口文档。

2.2.2.5. 【服务端】关闭订单

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

提示

关单没有时间限制，建议在订单生成后间隔几分钟（最短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          + "\"individual_auth_id\":\"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                        "individual_auth_id" => "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}
36

更多参数、响应详情及错误码请参见个人收款交易关单API 接口文档。

2.2.3. 订单状态流转图

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服