3. 开发指引

3.1 对接规范

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

SDK示例：Java SDK

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

3.2 业务开发配置

3.2.1 微信侧准备：

准备一个已认证的公众号（微信内置浏览器）、小程序（第三方浏览器唤醒用）

3.2.2 斗拱侧准备:

1. 微信：已开通微信业务，并配置小程序和公众号Appid
2. 商户微信实名认证状态已完成，实名认证状态显示已授权

1）通过服务商控台确认已完成实名认证：新版控台-服务商控台-【商户信息】

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

3）商家已反馈实际在微信认证通过（由于斗拱对接的微信接口可能存在更新延迟情况，可按照微信实际认证情况为准）

3.3 系统调用流程

H5支付方式的整体调用流程建议：

3.3.1 微信调用流程

主要有以下几个步骤：

• 通过授权获取用户 open_id
• 用前端获取的用户信息调斗拱聚合正扫接口；
• 聚合正扫接口返回的pay_info提供前端页面发起支付；
• 斗拱会将交易结果通知到商户后端系统。

接入步骤详细说明：

1. 通过授权获取用户 open_id

授权说明见微信官方链接： 网页授权

• 微信公众号后台配置授权域名，将微信校验文件放到服务器根目录下
• 用户静默授权获取code，前端页面在微信内打开授权地址，并重定向到自己项目目标地址

只为获取 open_id的话静默授权就可以，无需用户同意。

地址：

/*scope取值：snsapi_base/snsapi_userinfo 
    - snsapi_base （不弹出授权页面，直接跳转，只能获取用户openid）
    - snsapi_userinfo （弹出授权页面，可通过openid拿到昵称、性别、所在地。并且， 即使在未关注的情况下，只要用户授权，也能获取其信息 ）
*/
let url=`https://open.weixin.qq.com/connect/oauth2/authorize?appid=${appid}&redirect_uri=${urlNow}&response_type=code&scope=${scope}&state=STATE&connect_redirect=1#wechat_redirect`;
window.location.replace(url);复制代码复制失败复制成功

如果用户同意授权，页面将跳转至 redirect_uri/?code=CODE&state=STATE。

• 使用获取到的code，在服务端调用微信接口获取 access_token和 open_id

获取code后，请求以下链接获取access_token：

示例代码如下：

/*https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code*/

url = 'https://api.weixin.qq.com/sns/oauth2/access_token'
params = {
        'appid': app_id,
        'secret': 'wx_secret',
        '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')复制代码复制失败复制成功

1. 调用汇付聚合正扫接口

参见 聚合正扫

交易类型 trade_type 选T_JSAPI，用户子标识 sub_openid 填上一步获取的openid

将接口应答的支付信息pay_info返回前端页面

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

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

同步返回关注以下字段：

1. 发起支付

前端页面调用JSAPI 使用聚合正扫返回的pay_info内容发起支付。

示例代码：

WeixinJSBridge.invoke('getBrandWCPayRequest', {
                "appId": "wx2421b1c4370ec43b",
                "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支付后回到商家页面的能力微信逐步回收，可利用点金计划来承载。 参见点金计划说明。

1. 交易终态获取

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

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

3.3.2 H5页面三方浏览器支付流程

调用流程如下

接入步骤说明：

1. APP跳转微信小程序

下载微信SDK 并参考 微信官方说明 接入SDK。

配置准备：

• 在微信开放平台上有账号而且有通过的移动应用。
• 在微信公众平台有账号而且有小程序，最好发布为体验版本

• 在微信开放平台把对应的移动应用和小程序建立关联
• 调用代码

示例代码：以IOS 为例，安卓示例请参考微信官方说明。

//微信建议应用启动时调用
    [WXApi registerApp:@"wx_app_id"];//wx_app_id 为移动应用的appid
    ...
    ...
    ...
    //跳转小程序部分
    WXLaunchMiniProgramReq *launchMiniProgramReq = [WXLaunchMiniProgramReq object];
    launchMiniProgramReq.userName = @"gh_4fxxxxxx";  //待拉起的小程序原始Id
    launchMiniProgramReq.path = @"pages/index/index?query='test'";    ////拉起小程序页面的可带参路径，不填默认拉起小程序首页，对于小游戏，可以只传入 query 部分，来实现传参效果，如：传入 "?foo=bar"。
    launchMiniProgramReq.miniProgramType = WXMiniProgramTypePreview; //拉起小程序的类型
    [WXApi sendReq:launchMiniProgramReq];
    ...
    ...
    ...复制代码复制失败复制成功

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')复制代码复制失败复制成功

1. 下单请求支付信息

通过上面的App打开的path是’path/index’, 所以需要把App的onShow事件定义在page/index.js上

这里的options.scene是1069，这个场景id表示从app打开。

options.query.key1和options.query.key2就是app打开小程序传递的参数。

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

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

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

同步返回关注以下字段：

1. 小程序端发起支付

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

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

3.3.5 退款流程

完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。微信、支付宝、银联云闪付参见扫码交易退款接口；其它类型的交易退款参见线上交易退款接口。

关注以下请参：

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

3.3.6 对账流程

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

方案一：控台下载；

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

• 接口下载的对账文件包括以下四类：

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

3.3.7 异步通知

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

调用汇付接口时上送的异步通知地址为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/open/doc/api/#/shgl/shjj/api_shjj_wxshpz

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

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

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

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

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

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

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

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

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

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

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

1. 支付接口调用报错："resp_desc":"数据权限认证失败"

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

解决方案：

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

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

1. 为什么交易成功以后会收到 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' 表示交易成功-入账失败（非正常情况，可联系汇付技术人员确认排查）