微信小程序支付

最近更新时间：2023.7.25

1. 产品介绍

1.1 简介

微信小程序：商户自行申请的微信小程序，进行商品信息和订单管理，在用户确认商户订单信息后调用微信支付完成下单购买的流程。

1.2 应用场景

适用对象：开通了微信线上、线下小程序支付权限的商户；

汇付支持：

1. 小程序支付开通、小程序支付配置（小程序参数）、小程序支付（AT）、AT活动报名、手续费配置（内扣、外扣、实收、后收、线上、线下）；
2. 支持AT代金券、支持AT商家券;

微信小程序支付示例：

流程图：

2. 接入前准备

2.1 商务准备

1. 选择接入模式

2. 直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起商户入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。

3. 服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起服务商入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。

4. 在斗拱完成商户进件入网

   1. 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
   2. 服务商模式：
      1. 控台入网：参考服务商控台进件流程，渠道商接入指引；
      2. API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。

5. 选择接入功能并准备相关材料

   1. 微信支付：提供商户或服务商主体的小程序APPID;

2.2 对接准备

第一步：密钥获取

联调之前需要先获取公私钥，参见公私解钥参数获取说明；

第二步：公共参数获取

登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息;

第三步：业务开通及配置

• 服务商模式：

步骤一：服务商功能及权限开通。服务商通过线下签约方式申请微信功能，汇付运营人员在审核好服务商资料之后，为服务商开通相关支付功能，及费率配置。

步骤二：为商户开通功能及权限。服务商权限及费率配置完成后，服务商可在服务商控台为下属商户申请开通相关支付功能，或通过调用 商户业务开通 接口开通。具体流程请参考API文档，商户进件。

•  直签商户：

与客户经理确认已开通功能及相关费率及APPID配置。

3. 开发指引

3.1 对接规范

调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：

SDK示例：Java SDK

加签验签：v2版接口加签验签

3.2 确认业务配置

3.2.1 微信侧准备：

1. 商户在微信公众平台有账号而且有小程序，开发阶段可以使用体验版本进行测试，需要将小程序先上线，小程序上线需通过微信审核。

3.2.2 斗拱侧准备:

1. 商户微信小程序业务已开通、小程序appid已配置、小程序费率已配置；（如已与客户经理确认，该步骤可忽略）

查询方式

1）服务商控台：【商户信息】【查看】【商户变更】【业务信息】【基础支付】

2）商户控台：【我的信息】

3）通过微信配置查询接口来确认相关配置。

2. 商户微信实名认证状态已完成，实名认证状态显示已授权（微信侧实际完成即可，斗拱控台可能存在状态更新不及时）。

查询方式

1）服务商控台：【商户信息】

2）通过微信实名认证状态查询接口来确认相关配置。

3.3 系统调用流程

3.3.1 交易流程

接入步骤说明：

1. 通过授权获取用户 open_id a.小程序端调用 wx.login(Object object)接口 获取登录凭证（code）示例：

wx.login({
    success (res) {
        if (res.code) {
            //发起网络请求
            wx.request({
                url: 'https://test.com/onLogin',
                data: {
                code: res.code
                }
            })
        } else {
            console.log('登录失败！' + res.errMsg)
        }
    }
})复制代码复制失败复制成功

b. 商户服务端使用第一步获取的code 换取 open_id ，后台调用接口 获取openID 示例代码如下：

/*GET https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code*/

url = 'https://api.weixin.qq.com/sns/jscode2session'
params = {
        'appid': app_id,
        'secret': 'wx_secret',
        'js_code': wx_code,
        'grant_type': 'authorization_code',
}
resp = requests.get(url, params, timeout=15)
result_dict = json.loads(resp.text)
openid=result_dict.get('openid')复制代码复制失败复制成功

2. 商户服务端使用 open_id 下单

调用 聚合正扫 接口下单拉起支付，需要传入前端调用获得的 open_id 获取微信返回支付 pay_info信息。

聚合正扫接口需关注以下字段：

*其中wx_data中，如填写openid则无需填写sub_appid+sub_openid。如不填openid，则需填写sub_appid和sub_openid。

同步返回关注以下字段：

3. 小程序端发起支付

小程序端使用聚合正扫返回的pay_info 调用wx.requestPayment(OBJECT)发起微信支付。

    wx.requestPayment(
    {
        'timeStamp': '',
        'nonceStr': '',
        'package': '',
        'signType': 'MD5',
        'paySign': '',
        'success':function(res){},
        'fail':function(res){},
        'complete':function(res){}
    })复制代码复制失败复制成功

4. 交易终态获取

客户支付完成后汇付会将支付结果推送到客户异步地址，主要关注参数如下

如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态；

3.3.2 退款流程

完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。参见扫码交易退款接口；

关注以下请参：

• 原交易请求流水号、原交易全局流水号、原交易微信支付宝的商户单号三选一即可；
• 退款金额不能大于交易金额；由于接口支持多次部分退款，多次退款场景下退款总额不能高于原交易金额；
• 退款也是以异步返回的成功或失败状态为最终结果；
• 一些特殊场景下退款时效可能比较长，注意接口描述文档中的退款时效说明；

3.3.3 对账流程

为了满足商户财务的对账需求，斗拱提供了对账功能。

方案一：控台下载；

方案二：接口获取；参见交易结算对账单查询接口

• 接口下载的对账文件包括以下四类：
  • 日对账单类型：包括日结算对账单、日分账对账单、日出金对账单；
  • 日交易数据：主要是各种支付交易记录；
  • 月结算对账单：按月汇总的结算对账单；
  • 月交易数据：按月汇总支付交易记录；

3.3.4 异步通知

针对交易结果，汇付会通过异步消息的方式通知客户系统。 

调用汇付接口时上送的异步通知地址为http/https路径：服务器为POST回调，默认超时时间为5秒，超时后会重试3次；不支持HTTP重定向；服务器对应答不是200~300之间的错误，会默认重试3次；异步通知服务器对HTTPS不认证验签和ALLOW_ALL_HOSTNAME_VERIFIER；如商户自定义通知端口，请使用8000-9005内端口，否则无法通知；URL 上请勿附带参数；异步回调请求编码集为：UTF-8；收到通知后请返回状态码“200”,响应异步通知。

注意事项：

同样的异步消息可能会通知多次，因此接收异步消息的处理需做好幂等，保障多次接收到同样的消息处理后结果不变。

在实现异步消息接收的同时，都建议您在重要的业务环节，通过反查接口确认 非终态 支付订单的状态，以保证在发生异步消息延迟或无法送达情况下的支付结果一致性。

详见异步通知使用说明。

4. API列表

5.常见问题

1. 微信支付时，接口报错："sub_mch_id与sub_appid不匹配"

问题原因：微信公众号/小程序支付时报此错误，一般是商户未正确配置交易所使用的微信公众号/小程序 appid 到微信侧。

解决方案：

     1） 渠道商控台给商户配置，如下图：

      2） 通过接口配置： 

微信商户配置 https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxshpz

2. 微信支付时，接口报错:”当前商户需补齐相关资料后，才可进行相应的支付交易，请商户联系对接的微信支付服务商 ”

问题原因：此错误一般是商户还没有完成微信实名认证。

解决方案：完成微信实名认证

1).渠道商控台进行实名认证，菜单如图：

2).扫拓展码进行实名验证（可联系汇付人员指导）

3).通过接口进行实名认证：

实名认证接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz

3. 微信支付返回：redirect_uri域名与后台配置不一致

问题原因：网页授权页面未正确配置。

解决方案：登录服务商微信后台配置下网页授权域名。

微信后台 在 设置与开发 -> 公众号设置 -> 功能设置 中找到 网页授权域名

4. 支付接口调用报错：“resp_desc”：“数据权限认证失败”

问题原因：商户信息校验没有通过。

解决方案：

1）检查报文中的产品号（product_id）是否填写正确;

2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。

5. 为什么交易成功以后会收到 2 条异步通知？

2条异步通知分别是 交易异步 跟 账务异步，用 notify_type 字段区分。

1). 交易异步情况

notify_type='1'，trans_stat='F' 时，不推送账务异步

notify_type='1'，trans_stat='S' 时，会推送账务异步

2). 账务异步情况：

notify_type='2'，trans_stat='S'，acct_stat='S' 表示交易成功-入账成功

notify_type='2'，trans_stat='S'，acct_stat='F' 表示交易成功-入账失败（非正常情况，可联系汇付技术人员确认排查）

更多问题详见斗拱开发者社区：https://service.dougong.net/t/qa