微信支付

微信支付接入流程

商户号申请

用财务同事的微信号作为商户的超级管理员，来申请开通商户号，因为超管账号有操作资金的权限，这个账号不能由开发部门来负责，得由财务部门来负责。

会用到微信支付功能的网页，所属公众号是用子公司资料注册的，而微信支付的申请，财务的同事强烈建议用母公司的资料来做。这样就导致微信支付和公众号所关联的主体公司不同，在申请开通微信支付时，是没办法将公众号关联到商户号上的。只有在微信支付开通成功之后，用超管账号登录管理后台，手动关联才行。

商户号查看

在“微信支付商家助手”小程序中，点击首页顶部的公司名称，在打开的页面中，最上方的公司名称下面，就有商户号的编号。

商户号配置

【需超管】授权开发人员账号

对于开发人员，超级管理员还需为其账号授予下面三项权限，以便其顺利接入微信支付功能：

API 证书查看
API 证书续期
密钥修改

【需超管】绑定公众号 AppID

由于商户号是用母公司身份申请的，而需要关联的公众号 AppID 是用子公司身份申请的，为官方文档商户申请接入时，如何确认绑定关系？中所说的情况三：申请绑定主体不一致的 AppID。

先登录微信支付后台，依次进入产品中心 → AppID 账号管理，点击按钮“关联 AppID”，填写公众号的 AppID 和 AppID 认证主体这两项信息，并提交操作。

然后登录微信公众平台，点击左侧的“微信支付”，允许商户关联的请求。

【需超管】申请 API 证书

什么是商户API证书？如何获取商户API证书？

按照流程申请并下载证书及私钥文件，发送给开发人员，以便顺利接入微信支付功能。

接入前准备 - 4.下载并配置商户证书

注意事项：证书安全

接口规则 - 安全规范

证书文件不应放在 Web 服务器目录下，而应放在有访问权限控制的目录中，防止被他人下载；
建议将证书文件名改为复杂且不容易猜测的文件名，提升安全性；
服务器要做好病毒和木马防护工作，不被非法侵入者窃取证书文件。

【需授权】配置 API 密钥

参考文档

证书用途：涉及敏感操作时，比如资金回滚、退款、撤销等，需要用商户证书来校验机构身份。

【需超管】设置支付授权目录（公众号内前端页面）

参考文档

支付授权目录，就是会调用“微信支付收银台”的页面地址。

建议将其设置为带协议格式的顶级域名，比如：https://www.weixin.com/ ，这样只校验顶级域名，域名下的任何页面都可以调用微信支付功能，会比较方便。

设置授权域名（公众号关联的后端服务）

开发 JSAPI 支付功能时，在下单接口中必须要传用户的 openid。

要实现这一需求，就得在公众号中设置允许获取 openid 的域名，这样该域名才能合法获取 openid。

在公司的实际业务中，使用专门提供后端 API 服务的那个域名应该就可以？到时候验证一下。

微信支付整体流程

看懂了业务流程图，对于微信支付过程中，需要后端参与的部分就清楚了。其实主要就是下面几个关键步骤：

步骤3：用户下单发起支付，商户通过统一下单 API 创建支付订单。
步骤8：用户继续发起支付，商户通过 JSAPI 调起支付API 调起微信支付，用之前创建的支付订单发起支付请求。
步骤15：用户支付成功后，商户接收微信的支付结果通知 API 所发来的支付结果。
步骤20：如果商户没有接收到微信支付结果通知（4 小时），需要主动调用查询订单 API 查询支付结果。

微信支付 API v3

官方文档

JSAPI 支付 v2 旧版文档：有些内容在新版的 v3 文档中没有写，可以来旧版文档中找资料，比如下面统一下单的订单号的生成建议。

【服务端】统一下单

官方文档：统一下单 API

在实际项目中，直接使用了 TNWX 的示例代码。

其中的 case 13，就是后端根据用户传来的 OpenID，调用 JSAPI 支付方式的统一下单接口获取预支付订单号：{ "prepay_id": "wx201410272009395522657a690389285100" }。

然后根据预支付订单号再构造签名串、计算签名值，将这些信息返回给前端，因为这都是最终支付时所需要的，所以 case 13 中一次性将这些步骤都完成了，自己在实际项目中的代码也是如此操作的。

注意事项

订单号 ：应按什么规则生成？旧版文档中对于订单号的生成给出了建议：根据当前系统时间加随机序列来生成订单号。

交易结束时间 ：API 调用成功的话，返回的预支付交易会话标识有效期为 2 小时。所以调用该接口时，请求中的交易结束时间也设置为 2 小时？

通知地址 ：用于接收支付结果的接口地址，必须为 https，且应当能直接访问，不能携带查询字符串。

错误码 ：根据对应的错误码，在前端页面中给用户以相应提示。

【客户端】JSAPI 调起支付

官方文档：JSAPI 调起支付 API

后端生成支付所需签名串和签名的过程，也在 TNWX 的示例代码的 case 13 中。

前端拿到支付所需的各种数据之后，执行下面的代码，即可完成最终支付：

function onBridgeReady() {
  WeixinJSBridge.invoke('getBrandWCPayRequest', {
    //公众号名称，由商户传入
    "appId": "wx2421b1c4370ec43b",
    //时间戳，自1970年以来的秒数
    "timeStamp": "1395712654",
    //随机串
    "nonceStr": "e61463f8efa94090b1f366cccfbbb444",
    "package": "prepay_id=up_wx21201855730335ac86f8c43d1889123400",
    //微信签名方式：
    "signType": "RSA",
    //微信签名
    "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg=="
  },
  function(res) {
    if (res.err_msg == "get_brand_wcpay_request:ok") {
      // 使用以上方式判断前端返回,微信团队郑重提示：
      //res.err_msg将在用户支付成功后返回ok，但并不保证它绝对可靠。
    }
  });
}
if (typeof WeixinJSBridge == "undefined") {
  if (document.addEventListener) {
    document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
  } else if (document.attachEvent) {
    document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
    document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
  }
} else {
  onBridgeReady();
}

注意事项

JSAPI 是微信 APP 内的功能，调起支付 API 不需要请求外部接口。

另外，在上面的示例代码中，用的是 WeixinJSBridge.invoke('getBrandWCPayRequest', {}) 这个 API 发起支付。和 wx.chooseWXPay 相比，前者不需要引入 jweixin 这个文件，也不需要调用 wx.config 接口，来注入权限验证配置，更方便一些。

不过如果公众号还有其它需要调用微信 JS-SDK 的需求，那么还是需要引入 jweixin，也还是需要调用 wx.config 接口，来注入权限验证配置，这个就根据自己实际业务需求来判断。

参考资料：

金额计算/精度问题

如果用 JS 自带的方法计算金额，会出现精度丢失的问题，比如 69.1 * 100 计算出来的结果是 6909.999999999999。如果将这样的结果传给微信支付，就会报错：无法将 JSON 输入源“/body/amount/total”映射到目标字段“总金额”中，此字段需要一个合法的 64 位有符号整数。

务必要用 decimal.js 之类的库来计算金额，以确保最终计算出来的订单金额是整数（以“分”为单位）。

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

官方文档：支付通知API

注意事项

回调 URL：这里用于接收支付结果通知的回调 URL，就是在前面统一下单接口中，传给微信的“通知地址”字段。

通知规则：用户支付完成后，微信会把支付结果和用户信息发给该回调 URL，服务端保存该支付通知，并返回应答信息，以告知微信已成功接收到支付通知。

返回的应答如果不符合微信规范或返回超时，微信会以一定的频率重新发起通知： 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m。

签名验证

微信会对发给商户的通知进行签名，签名数据在 HTTP header 的 Wechatpay-Signature 字段中，缺失该字段或者字段值验签不通过，均视为不可信的回调请求。

具体的签名验证过程，见官方文档签名验证。

要验证收到的通知信息，首先需要 微信支付平台证书 中的公钥，注意，这个和前面提到过的商户 API 证书是不同的。

微信支付平台证书的获取方法见文档获取平台证书列表，其中 HTTP 请求头 Authorization 字段的值，按照文档签名生成中的方法生成即可。

在脚手架 TNWX 中，如果单纯设置 HTTP 请求头 Authorization 字段的值，调用 PayKit.buildAuthorization 方法即可。如果要获取平台证书列表，调用 PayKit.exeGet 方法即可。

如果调用“获取平台证书列表”接口成功，则响应头和响应体的数据如下：

// 响应头
{
  'wechatpay-nonce': '****',
  'wechatpay-signature': '****',
  'wechatpay-timestamp': '1612346036',
  'wechatpay-serial': '5157F09EFDC096DE15EBE81A47057A7232F1B8E1'
}

// 响应体
{
  "data": [
      {
          "serial_no": "5157F09EFDC096DE15EBE81A47057A7232F1B8E1",
          "effective_time ": "2018-06-08T10:34:56+08:00",
          "expire_time ": "2018-12-08T10:34:56+08:00",
          "encrypt_certificate": {
              "algorithm": "AEAD_AES_256_GCM",
              "nonce": "61f9c719728a",
              "associated_data": "certificate",
              "ciphertext": "sRvt… "
          }
      },
      {
          "serial_no": "50062CE505775F070CAB06E697F1BBD1AD4F4D87",
          "effective_time ": "2018-12-07T10:34:56+08:00",
          "expire_time ": "2020-12-07T10:34:56+08:00",
          "encrypt_certificate": {
              "algorithm": "AEAD_AES_256_GCM",
              "nonce": "35f9c719727b",
              "associated_data": "certificate",
              "ciphertext": "aBvt… "
          }
      }
  ]
}

TODO: 那么是否要根据文档证书和回调报文解密中所说的步骤，对证书进行解密？但是响应体会返回多个证书，对哪个证书进行解密？是只解密响应头 wechatpay-serial 中所记录的那个证书就行？

报文解密

对于验签通过的回调，再对 HTTP body 进行解密。

商户平台上设置的 API v3 密钥为 key
回调 HTTP body 中的 resource.algorithm 中为算法（目前为AEAD_AES_256_GCM）
用上面的 key 和 HTTP body 中的 resource.nonce 和 resource.associated_data 作为算法的参数，对 HTTP body 中的密文 resource.ciphertext 进行解密，就得到了 JSON 格式的原始通知内容

拿到了通知的原始内容后，主要看交易状态字段 trade_state 的值，根据该值的内容，进行对应的处理。最简单的当然是支付成功了，但是其他情况也要处理。

金额问题

微信返回的支付结果中，amount.total 和 amount.payer_total 的值可能不一样，后者是用户使用了各种券之后的实际支付金额。

通知应答

如果回调处理异常，服务端返回给微信的 HTTP 状态码应当是 4XX 或者 500。

只有返回 200 或 204，微信才认为服务端正常接收到了支付结果的通知。

商户后台应答失败（商户失败？微信失败？）时，微信支付会记录应答的报文（HTTP body），建议商户用下面的格式返回。

{   
    "code": "ERROR_NAME",
    "message": "ERROR_DESCRIPTION",
}

处理重复通知

from 官方文档：

同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

Postman 脚本

微信支付API v3 Postman脚本

参考资料

在 V2EX、掘金、思否等社区查找有价值的文档。

GitHub 上的一个用 TypeScript 写的微信平台开发脚手架：Javen205 / TNWX 挺不错，提供了微信平台开发的各方面功能，在项目中用上了。

未使用：

GitHub 上有个用 TS 写的项目：klover2 / wechatpay-node-v3-ts，是用于微信支付 API v3 版本的，看看代码，可以的话就直接应用到项目里。
Gitee 上有个两年没更新的项目，也是用 TS 写的，同时支持微信支付和支付宝支付，也可以借鉴：Notadd / nt-addon-pay。

结算费率及入账周期

结算费率

费率：微信支付每笔交易收取的手续费，单位为“元”。出版社可选择的行业（符合资质要求或没有资质限制的），对应的费率为 0.6% 或 1%。

入账周期

入账周期：微信支付将交易款项划入商户账户的时间，单位为“天”。企业的入账周期全都是 T+1。

虚拟限额

虚拟限额：对于虚拟业务，微信支付有虚拟限额存在，该限额仅限制用户付款，不限制商户收款。单用户每笔付款限额 6000，每天限额 9000。有虚拟限额的业务不多，可以在小程序里把服务类目切换成其他的，就不会有虚拟限额了。

官方文档

入驻结算规则、行业属性及特殊资质：列出了各类主体（企业、事业单位、政府等）在开通微信支付时，可选择的行业及对应的结算费率和入账周期。
商户收款限额是多少？

问题记录

风险异常 —— 交易停滞

财务同事有一天说公司微信支付账号出现异常情况。

登录微信支付后台，提示风险类型为“交易停滞”，处理方法为“调整收款额度（单日10000元），关闭信用卡支付权限”。

按照官方页面的提示进入小程序，发现交易停滞的原因如下：

此商户由于近期未产生任何交易，存在经营异常情况，平台判定存在风险。如您目前有使用该商户号进行经营的诉求，请提交相关材料。平台将于7日内完成审核，审核通过后自动解除处罚

按照流程指引完成了解除处罚的申请，然后就是等待审核结果了。

关键名词

商户 API 证书

用途

商户调用微信支付所有接口都需要用到该证书，比如下单接口、订单查询接口等。微信支付后台用于识别商户真实身份。

证书更新

商户 API 证书有效期为 5 年，可访问该页面查看证书的有效期。

证书更新流程可查看该页面，新证书申请并部署成功后，记得作废旧证书。

目前商户 API 证书只能通过 网页端 + 单机软件 更新，不支持 API 更新。

平台证书

用途

微信支付验证商户的请求签名正确后，会在应答的HTTP头部中包括 应答签名。
微信支付会在回调的 HTTP 头部中带上 回调报文的签名。

对于微信返回的这两类签名，商户需要用 微信支付平台证书 中的公钥来验证签名的正确性。

证书更新

平台证书有效期为 5 年，可调用获取平台证书这个接口查看证书的有效期。

获取平台证书这个接口同时也可以用来下载证书。

商户 API 证书 vs. 平台证书

简而言之，商户 API 证书 是微信用来验证商户身份的，微信支付平台证书 是商户用来验证微信身份的。

也可以查看私钥和证书这篇官方文档。

参考资料

微信支付 API v3 接口文档

微信支付接入流程​

商户号申请​

商户号查看​

商户号配置​

【需超管】授权开发人员账号​

【需超管】绑定公众号 AppID​

【需超管】申请 API 证书​

注意事项：证书安全​

【需授权】配置 API 密钥​

【需超管】设置支付授权目录（公众号内前端页面）​

设置授权域名（公众号关联的后端服务）​

微信支付整体流程​

微信支付 API v3​

【服务端】统一下单​

注意事项​

【客户端】JSAPI 调起支付​

注意事项​

金额计算/精度问题​

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

注意事项​

签名验证​

报文解密​

金额问题​

通知应答​

处理重复通知​

Postman 脚本​

参考资料​

结算费率及入账周期​

结算费率​

入账周期​

虚拟限额​

官方文档​

问题记录​

风险异常 —— 交易停滞​

关键名词​

商户 API 证书​

用途​

证书更新​

平台证书​

用途​

证书更新​

商户 API 证书 vs. 平台证书​

参考资料​

微信支付接入流程

商户号申请

商户号查看

商户号配置

【需超管】授权开发人员账号

【需超管】绑定公众号 AppID

【需超管】申请 API 证书

注意事项：证书安全

【需授权】配置 API 密钥

【需超管】设置支付授权目录（公众号内前端页面）

设置授权域名（公众号关联的后端服务）

微信支付整体流程

微信支付 API v3

【服务端】统一下单

注意事项

【客户端】JSAPI 调起支付

注意事项

金额计算/精度问题

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

注意事项

签名验证

报文解密

金额问题

通知应答

处理重复通知

Postman 脚本

参考资料

结算费率及入账周期

结算费率

入账周期

虚拟限额

官方文档

问题记录

风险异常 —— 交易停滞

关键名词

商户 API 证书

用途

证书更新

平台证书

用途

证书更新

商户 API 证书 vs. 平台证书

参考资料