网银支付
最近更新时间：2023.11.20
1. 产品介绍
1.1 简介
网银支付主要适用于企业用户和个人用户在商户页面进行B2B或B2C支付的场景。企业用户或个人用户在商户页面通过点击支付图标，然后跳转到汇付网银支付银行选择页面点击相应银行图标，或直接在商户页面点击相应银行的网银图标，跳转至账户发行方网银页面后，进行付款操作，完成支付。
1.2 应用场景
该产品主要应用于境内商户的企业线上B2B交易和个人B2C支付，适用场景包括电子商务、行业供应链、企业采购、招投标支付、公共服务支付、物流保险等领域。
样例
a) 付款人浏览商户购物网站，选择商品；
b) 付款人在商户购物网站确认商品，并提交订单；
c) 付款人在银行列表选择所要支付的银行（如果是企业，则在企业网银银行列表页面选择所要支付的银行，企业网银支付有经办和复核两个环节）；
d) 付款人在银行页面完成支付；
注：付款人的银行卡需要预先在银行网银或柜面开通网银支付功能可进行支付。
可进行斗拱演示体验，了解网银支付的效果。
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，商户需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为商户发起入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，服务商需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为服务商发起入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
在斗拱完成商户进件入网
-
直签模式：已有汇付销售人员申请开通，商户无须另行操作；
-
服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息（如控台未展示，可群内咨询汇付技术人员获取）;
第三步：业务开通及配置
- 服务商/代理商开通
服务商或代理商通过线下签约方式申请网银功能；
运营人员在审核好服务商资料之后，为服务商开通网银支付功能，及费率配置；
- 商户开通
可以通过服务商控台和接口两种方式为商户开通网银支付功能权限；
- 通过服务商控台申请
服务商通过服务商控台为商户申请网银支付功能
服务商控台-商户管理-商户信息-操作“查看”-业务信息“编辑”-支付功能
第一步，在商户信息页面点击“查询”，在下方列表这种选择要开通功能的商户，点击“查看”，进入功能查看和申请页面；
第二步，在“商户详情”页面点击“编辑”，进入“业务信息编辑”页面；
第三步，在“业务信息编辑”页面在“支付功能”选择开通“网银支付”，申请开通时需要配置商户的B2C（个人网银）贷记卡、B2C（个人网银）借记卡和B2B（企业网银）的费率，并选择“商户业务类型”，每个业务类型对应的申请材料各不相同，详见2.2.1申请资料章节，并提交资料，点击“确定提交”就可进入汇付功能审核环节，汇付运营人员在4个小时内审核完成；
- 通过接口申请
调用 商户业务开通 接口开通。具体流程请参考API文档，商户进件。
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
登录控台查询商户网银支付是否配置完成
-
服务商控台-【商户管理】-【商户信息】-操作“查看”-支付功能
-
商户控台-【我的信息管理】-【我的信息】-业务信息
- 通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
商户调用网银流程说明
商户可根据需求自由选择支付模式：
- 模式一：调接口展示斗拱的银行选择页面，展示商户在控台配置好的所有银行，客户选完银行后展示银行网银页面。
- 模式二：调接口时指定银行，斗拱页面只显示指定的银行，用户按要求通过指定银行支付。
两种模式可通过网银支付接口的bank_id(付款方银行编号)区分，不上送bank_id代表模式一，商户获取斗拱平台的银行选择页面html；上送bank_id代表模式二，商户获取指定的银行网银页面html。
接入步骤：
a) 商户调用网银支付接口，提交订单：
b) 客户选择对应银行，唤起银行网银支付页面；
c) 客户完成支付操作；
d) 银行系统会异步通知汇付支付状态；
e) 汇付异步通知商户支付状态；
查询
a) 商户调用线上交易查询接口，上传原交易日期、原交易订单号等信息查询该订单交易结果；
b) 汇付斗拱系统同步返回该笔网银支付订单交易结果；
网银支付接口需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| time_expire | 订单失效时间 | N | 格式yyyyMMddHHmmss；示例值：20221102202234 （注：工商银行需传90min以上方能成功）；不传默认5小时； |
| gate_type | 网关支付类型 | N | 01: 个人网关，02: 企业网关，不传值，默认：01（个人网关）；示例值：01 |
| bank_id | 付款方银行编号 | N | 若填入付款方银行编号时，同步返回具体银行页面； 若未填入付款方银行编号时，同步返回银行选择页面 |
| notify_url | 异步通知地址 | Y | 交易结果异步通知地址，格式以http或https开头。 示例值：https://callback.service.com/xx |
3.3.2 退款流程
a) 商户调用线上交易退款接口，向汇付发起退款；
b) 汇付判断商户收款账户中是否资金满足本次退款金额；
c) 汇付向银行发起退款请求；
d) 银行返回退款请求结果给到汇付；
e) 汇付同步返回退款请求状态给到商户；
f) 银行端异步返回退款结果给到汇付；
g) 汇付异步返回退款结果给到商户；
退款查询：调用线上退款查询接口，上传原退款请求日期、原退款交易流水号、进行退款交易结果查询；
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.常见问题
- 关单时间：商户传time_expire 订单失效时间（注：工商银行需传90min以上方能成功），超过时间会将该笔订单进行失效处理。不传默认5小时。
- 浏览器兼容性：建议使用IE11及以上系统，Google、火狐浏览器，不建议使用包括360、QQ浏览器；
- 限额及支持银行：详见支持银行限额Excel；
更多问题详见斗拱开发者社区：https://service.dougong.net/t/qa
