H5页面微信支付
最近更新时间:2023.10.31
1. 方案介绍
1.1 应用场景
商户拥有一个H5商城或通过H5页面对外提供线上服务,当需要收款时调用斗拱SAAS支付接口完成收款,下图是微信、支付宝、银联云闪付、手机默认浏览器环境下可以使用的H5页面收款效果。
可以通过斗拱演示体验了解在H5网页中支付演示效果,演示程序自动识别当前的环境是微信、支付宝、银联云闪付还是默认浏览器,程序会自动根据环境展示适用的支付方式;下图是演示H5页面的链接。
1.2 名词定义及说明
由于微信和支付宝未开放给三方机构原生H5支付能力,故汇付是如下实现H5支付
【微信H5支付】:通过微信JSAPI支付(JSAPI支付-产品介绍 |微信支付商户平台文档中心 (qq.com))实现,利用微信公众号接口进行调用和支付
【第三方浏览器H5支付】:仅支持支付宝、微信,支付宝通过Native形式实现,微信通过唤醒微信小程序方式实现
更多名词解释,请参考:名词解释说明
2. 接入前准备
2.1 商务准备
-
商户已有H5商城网站或服务,并且已经过ICP备案;
-
选择接入模式
-
直签模式:指商户与汇付直接签约。具体流程:商户完成协议签署后,将准备好的入网材料提供给汇付销售人员,由汇付销售人员发起商户入网申请,待审核通过入网成功后,商户联系人将收到短信通知控台账号及密码。
-
服务商模式:指服务商与汇付签约,服务商通过接口或控台方式完成商户入网。具体流程:服务商完成协议签署后,将准备好的入网材料提供给汇付销售人员,由汇付销售人员发起服务商入网申请,待审核通过入网成功后,服务商联系人将收到短信通知控台账号及密码。
-
-
在斗拱完成商户进件入网
- 直签模式:已有汇付销售人员申请开通,商户无须另行操作;
- 服务商模式:
- 控台入网:参考服务商控台进件流程,渠道商接入指引;
- API入网:
- 企业商户调用 企业商户基本信息入驻接口 、小微商户调用 个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
- 调用 商户业务开通 开通微信/支付宝/银联云闪付入驻。具体流程请参考文档商户进件。
-
选择接入功能并准备相关材料
- 微信H5支付:提供商户或服务商主体的公众号,并在汇付开通微信支付业务并配置公众号appid;
- 第三方浏览器H5支付:跳转支付宝可使用native模式实现,跳转微信可使用小程序模式实现;
2.2 对接准备
第一步:密钥获取
联调之前需要先获取公私钥,参见公私解钥参数获取说明;
第二步:公共参数获取
登录服务商/商户控台后,可在开发设置-开发者信息中,获取sys_id,product_id参数信息;
第三步:业务开通及配置
- 服务商模式:
步骤一:服务商功能及权限开通。服务商通过线下签约方式申请支付宝或微信、银联云闪付功能,汇付运营人员在审核好服务商资料之后,为服务商开通相关支付功能,及费率配置。
步骤二:为商户开通功能及权限。服务商权限及费率配置完成后,服务商可在服务商控台为下属商户申请开通相关支付功能,或通过调用 商户业务开通 接口开通。具体流程请参考文档商户进件。
- 直签商户:
与客户经理确认已开通功能及相关费率配置。
3. 开发指引
3.1 对接规范
调用汇付接口,均采取POST形式提交,数据格式统一为JSON格式,相关SDK及签名方法见链接:
SDK示例:Java SDK
加签验签:v2版接口加签验签
3.2 业务开发配置
3.2.1 微信侧准备:
准备一个已认证的公众号(微信内置浏览器)、小程序(第三方浏览器唤醒用)
3.2.2 斗拱侧准备:
-
微信:已开通微信业务,并配置小程序和公众号Appid
-
商户微信实名认证状态已完成,实名认证状态显示已授权
1)通过服务商控台确认已完成实名认证:新版控台-服务商控台-【商户信息】
2)通过微信实名认证状态查询接口来确认相关配置
3)商家已反馈实际在微信认证通过(由于斗拱对接的微信接口可能存在更新延迟情况,可按照微信实际认证情况为准)
3.3 系统调用流程
H5支付方式的整体调用流程建议:
3.3.1 微信调用流程
主要有以下几个步骤:
-
通过授权获取用户 open_id
-
用前端获取的用户信息调斗拱聚合正扫接口;
-
聚合正扫接口返回的pay_info提供前端页面发起支付;
-
斗拱会将交易结果通知到商户后端系统。
接入步骤详细说明:
- 通过授权获取用户 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')
- 调用汇付聚合正扫接口
参见 聚合正扫
交易类型 trade_type 选T_JSAPI,用户子标识 sub_openid 填上一步获取的openid
将接口应答的支付信息pay_info返回前端页面
聚合正扫接口需关注以下字段:
参数 | 中文名 | 必填 | 说明 |
---|---|---|---|
trade_type | 交易类型 | Y | T_JSAPI: 微信JS支付 |
time_expire | 交易有效期 | N | 指定交易失效时间,不指定微信默认是2小时,超过有效时间的订单会默认被关闭 |
+wx_data | 微信拓展参数集合 | N | 通过前端调服微信获取的数据换取pay_info; |
sub_appid | 子商户公众账号ID | N | 微信公众号ID |
openid | 用户标识 | Y | 前端调用微信获取的用户在商户appid下的唯一标识; |
sub_openid | 子商户用户标识 | N | 前端调用微信获取的用户在子商户appid下的唯一标识; |
notify_url | 异步通知地址 | N | 交易异步通知地址,http或https开头 |
*其中wx_data中,如填写openid则无需填写sub_appid+sub_openid。如不填openid,则需填写sub_appid和sub_openid。
同步返回关注以下字段:
参数 | 中文名 | 说明 |
---|---|---|
trans_stat | 交易状态 | 同步通常返回“处理中”,交易终态以异步返回为准 |
resp_desc | 业务响应信息 | 关注失败原因 |
bank_message | 通道返回描述 | 关注通道返回的失败原因 |
pay_info | 支付信息 | 这个字段后续调用微信需要用到的 |
hf_seq_id | 全局流水号 | 汇付系统生成全局流水号,后续可以用这个流水号查询交易 |
- 发起支付
前端页面调用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支付后回到商家页面的能力微信逐步回收,可利用点金计划来承载。 参见微信说明。
- 交易终态获取
客户支付完成后汇付会将支付结果推送到客户异步地址,主要关注参数如下
参数 | 中文名 | 说明 |
---|---|---|
settlement_amt | 结算金额 | 用户实际支付金额。如有优惠该金额小于交易金额; |
fee_amount | 手续费金额 | 斗拱扣收的支付手续费金额 |
trans_stat | 交易状态 | 交易的最终结果;S:成功、F:失败 |
out_trans_id | 用户账单上的交易订单号 | ++交易在微信侧的流水号,参见用户账单说明++ |
party_order_id | 用户账单上的商户订单号 | ++交易在微信侧生成的订单号;参见用户账单说明++ |
wx_user_id | 微信用户唯一标识码 | 用户在微信侧的ID号 |
wx_response | 微信返回的响应报文 | Json格式 |
bank_message | 通道返回描述 | 如交易失败可以关注一下通道返回的错误描述 |
如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态;
3.3.2 第三方浏览器H5支付流程
调用流程如下
接入步骤说明:
- APP跳转微信小程序
配置准备:
- 在微信开放平台上有账号而且有通过的移动应用。
- 在微信公众平台有账号而且有小程序,最好发布为体验版本
- 在微信开放平台把对应的移动应用和小程序建立关联
- 调用代码
示例代码:以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];
...
...
...
- 通过授权获取用户 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')
- 下单请求支付信息
通过上面的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信息。
聚合正扫接口需关注以下字段:
参数 | 中文名 | 必填 | 说明 |
---|---|---|---|
trade_type | 交易类型 | Y | T_MINIAPP: 微信小程序 |
time_expire | 交易有效期 | N | 指定交易失效时间,不指定微信默认是2小时,超过有效时间的订单会默认被关闭 |
+wx_data | 微信拓展参数集合 | N | 通过前端调服微信获取的数据换取pay_info; |
sub_appid | 子商户公众账号ID | N | 微信小程序app_id |
openid | 用户标识 | Y | 前端调用微信获取的用户在商户appid下的唯一标识; |
sub_openid | 子商户用户标识 | N | 前端调用微信获取的用户在子商户appid下的唯一标识; |
notify_url | 异步通知地址 | N | 交易异步通知地址,http或https开头 |
*其中wx_data中,如填写openid则无需填写sub_appid+sub_openid。如不填openid,则需填写sub_appid和sub_openid。
同步返回关注以下字段:
参数 | 中文名 | 说明 |
---|---|---|
trans_stat | 交易状态 | 同步通常返回“处理中”,交易终态以异步返回为准 |
resp_desc | 业务响应信息 | 关注失败原因 |
bank_message | 通道返回描述 | 关注通道返回的失败原因 |
pay_info | 支付信息 | 这个字段后续调用微信需要用到的 |
hf_seq_id | 全局流水号 | 汇付系统生成全局流水号,后续可以用这个流水号查询交易 |
- 小程序端发起支付
使用聚合正扫返回的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 退款流程
完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时,商户可以通过本接口将支付款退还给用户,退款成功资金将原路返回。微信、支付宝、银联云闪付参见扫码交易退款接口;其它类型的交易退款参见线上交易退款接口。
关注以下请参:
参数 | 中文名 | 必填 | 说明 |
---|---|---|---|
org_req_date | 原交易请求日期 | Y | 用户发起支付的日期 |
org_req_seq_id | 原交易请求流水号 | C | 商户系统发给斗拱的指令流水号 |
org_hf_seq_id | 原交易全局流水号 | C | 汇付生成的系统流水号 |
org_party_order_id | 原交易微信支付宝的商户单号 | C | 该笔交易在微信支付宝端的流水号 |
ord_amt | 申请退款金额 | Y | 退款金额<=原交易金额 |
- 原交易请求流水号、原交易全局流水号、原交易微信支付宝的商户单号三选一即可;
- 退款金额不能大于交易金额;由于接口支持多次部分退款,多次退款场景下退款总额不能高于原交易金额;
- 退款也是以异步返回的成功或失败状态为最终结果;
- 一些特殊场景下退款时效可能比较长,注意接口描述文档中的退款时效说明;
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列表
类型 | 功能 | 描述 |
---|---|---|
API | 聚合正扫 | 商户服务端调该接口传入pay_info完成最终交易; |
API | 交易查询 | 查询支付交易信息 |
API | 交易退款 | 申请退款 |
API | 交易退款查询 | 查询退款进度及结果 |
API | 交易关单 | 长时间未支付做关单处理 |
API | 交易关单查询 | 交易关单查询 |
API | 微信用户标识查询 | 辅助类接口,微信用户标识查询 |
5.常见问题
- 微信支付时,接口报错:"sub_mch_id与sub_appid不匹配"
问题原因:微信公众号/小程序支付时报此错误,一般是商户未正确配置交易所使用的微信公众号/小程序 appid 到微信侧。
解决方案:
1) 渠道商控台给商户配置,如下图:
2) 通过接口配置:
微信商户配置 https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxshpz
- 微信支付时,接口报错:”当前商户需补齐相关资料后,才可进行相应的支付交易,请商户联系对接的微信支付服务商 ”
问题原因:此错误一般是商户还没有完成微信实名认证。
解决方案:完成微信实名认证
1).渠道商控台进行实名认证,菜单如图:
2).扫拓展码进行实名验证(可联系汇付人员指导)
3).通过接口进行实名认证:
实名认证接口:https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz
- 微信支付返回:redirect_uri域名与后台配置不一致
问题原因:网页授权页面未正确配置。
解决方案:登录服务商微信后台配置下网页授权域名。
微信后台 在 设置与开发 -> 公众号设置 -> 功能设置 中找到 网页授权域名
- 支付接口调用报错:“resp_desc”:“数据权限认证失败”
问题原因:商户信息校验没有通过。
解决方案:
1)检查报文中的产品号(product_id)是否填写正确;
2)检查报文中的系统号(sys_id)和商户号(huifu_Id) 从属关系是否正确。
- 为什么交易成功以后会收到 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