手机WAP支付
最近更新时间：2023.10.31
1. 产品介绍
1.1 简介
消费者在APP端或H5网页浏览，确认订单后，在收银台上选择手机WAP支付，供消费者用手机扫码支付。
1.2 应用场景
适用对象：开通手机WAP支付权限的商户;
客户选择商品后，提交订单，进入收银台，选择手机WAP支付方式，如下图;
可以通过斗拱收款演示网站下载演示APP或扫码打开H5演示页面体验手机WAP付款的效果;
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起商户入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起服务商入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
在斗拱完成商户进件入网
- 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：
- 企业商户调用 企业商户基本信息入驻接口 、小微商户调用 个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息；
第三步：业务开通及配置
- 服务商/代理商开通
服务商或代理商通过线下签约方式申请手机WAP功能；
运营人员在审核好服务商资料之后，为服务商开通手机WAP支付功能，及费率配置；
- 商户开通
可以通过服务商控台和接口两种方式为商户开通手机WAP支付功能权限；
- 通过服务商控台申请
服务商通过服务商控台为商户申请手机WAP支付功能
服务商控台-商户管理-商户信息-操作“查看”-业务信息“编辑”-支付功能
第一步，在商户信息页面点击“查询”，在下方列表这种选择要开通功能的商户，点击“查看”，进入功能查看和申请页面；
第二步，在“商户详情”页面点击“编辑”，进入“业务信息编辑”页面；
第三步，在“业务信息编辑”页面在“支付功能”选择开通“手机WAP支付”，申请开通时需要配置商户的手机WAP贷记卡与借记卡费率。点击“确定提交”就可进入汇付功能审核环节，汇付运营人员在4个小时内审核完成；
- 通过接口申请
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
- 商户业务已开通、费率已配置；（如已与客户经理确认，该步骤可忽略）
查询方式
1）服务商控台：【商户信息】【查看】【商户变更】【业务信息】【基础支付】
2）商户控台：【我的信息】
3）通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
调用步骤：
a) 商户调用手机WAP支付接口，提交订单；
b) 接口返回html支付页面，商户展示页面；
c) 客户完成支付操作，前端跳转回商户指定成功或失败页面；
d) 汇付异步通知商户服务端支付状态；
手机WAP接口需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| extend_pay_data | 网联扩展数据 | Y | jsonObject格式；参见银行扩展信息 |
| bank_card_no | 银行卡号 | N | instalments_num不为空时必填；示例值：6228480031509440000 |
| time_expire | 交易有效期 | N | 订单失效时间，格式：yyyyMMddHHmmss；示例值：20221022134523 |
| front_url | 页面跳转地址 | Y | 支付成功后，前端跳转地址； |
| front_fail_url | 页面失败跳转地址 | N | http地址，支付失败时，页面跳转至商户该URL（不带交易信息，仅跳转）； |
同步返回关注以下字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| form_html | 银行提交页面html | 用户前端展示 |
| form_encoding | 页面字符集 | UTF-8、GBK等等； |
| bank_code | 银行返回码 | 示例值：00 |
| bank_message | 通道返回描述 | 关注通道返回的失败原因 |
交易终态获取
客户支付完成后汇付会将支付结果推送到客户异步地址，主要关注参数如下
| 参数 | 中文名 | 说明 |
|---|---|---|
| trans_amt | 交易金额 | 单位元，需保留小数点后两位 |
| fee_amt | 手续费金额 | 斗拱扣收的支付手续费金额 |
| trans_stat | 交易状态 | 交易的最终结果；S：成功、F：失败 |
| bank_code | 通道返回码 | |
| bank_message | 通道返回描述 | 如交易失败可以关注一下通道返回的错误描述 |
如果长时间未收到异步结果可以调用线上交易查询查询交易状态；
3.3.2 退款流程
完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。参见线上交易退款接口；
关注以下请参：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原交易请求日期 | Y | 用户发起支付的日期 |
| org_req_seq_id | 原交易请求流水号 | C | 商户系统发给斗拱的指令流水号 |
| org_hf_seq_id | 原交易全局流水号 | C | 汇付生成的系统流水号 |
| ord_amt | 申请退款金额 | Y | 退款金额<=原交易金额 |
- 原交易请求流水号、原交易全局流水号二选一即可；
- 退款金额不能大于交易金额；由于接口支持多次部分退款，多次退款场景下退款总额不能高于原交易金额；
- 退款也是以异步返回的成功或失败状态为最终结果；
- 一些特殊场景下退款时效可能比较长，注意接口描述文档中的退款时效说明；
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列表
| 类型 | 功能 | 描述 |
|---|---|---|
| 应用程序接口 | 手机WAP支付 | 支持个人手机网页支付 |
| 应用程序接口 | 线上交易查询 | 用于查询单笔线上交易状态及明细 |
| 应用程序接口 | 线上交易退款 | 用于查询线上交易全额或部分退款 |
| 应用程序接口 | 线上交易退款查询 | 用于查询单笔线上退款状态及明细 |
5.常见问题
- 支付接口调用报错：“resp_desc”：“数据权限认证失败”
问题原因：商户信息校验没有通过。
解决方案：
1）检查报文中的产品号（product_id）是否填写正确;
2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。
