H5页面支付宝支付

1. 方案介绍

1.1 应用场景

商户拥有一个H5商城或通过H5页面对外提供线上服务，当需要收款时调用斗拱SAAS支付接口完成收款，下图是微信、支付宝、银联云闪付、手机默认浏览器环境下可以使用的H5页面收款效果。

可以通过斗拱演示体验了解在H5网页中支付演示效果，演示程序自动识别当前的环境是微信、支付宝、银联云闪付还是默认浏览器，程序会自动根据环境展示适用的支付方式；

1.2 名词定义及说明

由于微信和支付宝未开放给三方机构原生H5支付能力，故汇付是如下实现H5支付

【支付宝H5支付】：通过支付宝native（支付宝开放平台 （alipay.com））形式实现支付

【第三方浏览器H5支付】：仅支持支付宝、微信，支付宝通过Native形式实现，微信通过唤醒微信小程序方式实现

更多名词解释，请参考：名词解释说明

2. 接入前准备

2.1 商务准备

1. 商户已有H5商城网站或服务，并且已经过ICP备案;

2. 选择接入模式

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

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

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

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

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

   1. 支付宝H5支付：在汇付开通支付宝支付业务；
   2. 第三方浏览器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 斗拱侧准备:

1. 已开通支付宝业务

2. 商户支付宝实名认证状态已完成，实名认证状态显示已授权

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

   

   2）通过支付宝实名申请单查询接口来确认相关配置

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

3.3 系统调用流程

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

3.3.1 支付宝调用流程

适用场景：

－ H5页面在第三方浏览器中通过统一下单方式拉起支付宝APP，供用户完成支付。

此种方式的主要原理：

• 通过拉起支付宝APP 然后调用支付宝内said为10000007的扫码功能来发起支付。前端拿到服务端返回的支付信息（qr_code），在 APP 内 通过打开第三方APP的方式打开此URL。

接入步骤：

1. 调用斗拱聚合正扫 接口trade_type = 'A_NATIVE' (支付宝正扫)；

2. 取出接口返回的qr_code，在 APP 内 通过打开第三方APP的方式打开如下URL，举例：

   alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001

Android示例代码：

    // 固定前缀
    String topic = "alipays://platformapi/startapp?saId=10000007&qrcode=";
    // 从汇付正扫接口获取的参数（以下值仅为示例）
    String qrcodeUrl = "https://qr.alipay.com/bax02911brluc2xieoph6001"
    // 字符串拼接
    String jumpUrl = topic + qrcodeUrl;
    // 按以上示例拼接得出结果
    // jumpUrl 为 alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001
    Intent intent = new Intent();
    intent.setAction("android.intent.action.VIEW");
    // jumpUrl 为先前示例中拼装的 url
    Uri contentUrl = Uri.parse(jumpUrl);
    intent.setData(contentUrl);
    activity.startActivity(intent);复制代码复制失败复制成功

IOS 示例代码：

    [[UIApplication sharedApplication]openURL:[NSURL URLWithString: jumpUrl]];复制代码复制失败复制成功

如需考虑未安装支付宝的情况，APP端可使用 webview，加载聚合正扫接口返回的链接（例：https://qr.alipay.com/bax02911brluc2xieoph6001 此种方式，如未安装支付宝客户端，会跳转到支付宝下载页面，引导用户安装下载。

RN的方式参考以下示例：

    linkurl = 'alipays://platformapi/startapp?saId=10000007&qrcode='+ {URL}
    Linking.openURL(linkurl);复制代码复制失败复制成功

Union App开发方式：

调用方式可以参考 Uni-app拉起方式说明

3.3.2 第三方浏览器H5支付流程

同上；

3.3.3 退款流程

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

关注以下请参：

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

3.3.4 对账流程

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

方案一：控台下载；

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

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

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. 支付接口调用报错：“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