反扫支付
1. 产品介绍
1.1 简介
反扫指商家使用扫码枪、收银扫码器等设备，扫描顾客出示的支付码，进行交易。
斗拱的反扫支付服务更适用于大型商城、超市、连锁店等场所，商户可以将反扫服务集成到自有收银系统或收款设备中，消费者消费时，出示付款二维码，商家使用扫码设备进行扫码收款。
汇付提供扫码支付开通或修改、支付配置功能，聚合了支付宝、微信、银联二维码（云闪付）、数字货币支付等主流支付通道。并将交易信息反馈到商户业务系统中，实现信息流与资金流的统一。
1.2 应用场景
适用对象：开通微信、支付宝、银联二维码（云闪付）、数字人民币权限的商户；
汇付支持：
- 手续费配置（内扣、外扣、实收、后收、线上、线下）；
- 支持间连和直连扫码类型、支持指定子账户入金、支持ATU代金券;
反扫支付示例：
商家通过扫码设备，扫描消费者出示的付款码完成收款；
流程图：
1.3 名词定义及说明
【反扫】指客户出具二维码，由商家利用扫码设备扫描二维码进行收款的支付方式；
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起商户入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起服务商入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
在斗拱完成商户进件入网
- 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息;
第三步：业务开通及配置
- 服务商模式：
步骤一：服务商功能及权限开通。服务商通过线下签约方式申请支付宝或微信、银联云闪付功能，汇付运营人员在审核好服务商资料之后，为服务商开通相关支付功能，及费率配置。
步骤二：为商户开通功能及权限。服务商权限及费率配置完成后，服务商可在服务商控台为下属商户申请开通相关支付功能，或通过调用商户业务开通接口开通。具体流程请参考API文档，商户进件。
- 直签商户：
与客户经理确认已开通功能及相关费率配置。
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
控台查询微信、支付宝、银联二维码支付是否配置完成
- 渠道商控台-【商户管理】-【商户信息】-基础支付配置
2、路径：渠道商控台-【商户管理】-【商户支付功能管理】-查看数字货币
3、商户控台-【我的信息管理】-【我的信息】-业务信息
- 通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
- 消费者打开微信、支付宝、银联、数字货币APP，展示付款码；
- 商户收银员通过扫码枪等收银工具扫码读取付款码信息；
- 商户业务系统调用斗拱的【聚合反扫接口】将业务订单信息、微信/支付宝/银联/数字货币的付款码、设备信息传入即可。
聚合反扫接口需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| auth_code | 支付授权码 | Y | 收银设备读取的付款码 |
| wx_data | 微信参数集合 | N | 按微信要求填写 |
| alipay_data | 支付宝扩展参数集合 | N | 按支付宝要求填写 |
| unionpay_data | 银联参数集合 | N | 按银联要求填写 |
| risk_check_data | 安全信息 | Y | 机具的ip或经纬度 |
| terminal_device_info | 设备信息 | N | 设备信息 |
| notify_url | 异步通知地址 | N | 交易异步通知地址，http或https开头 |
同步返回关注以下字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| trans_stat | 交易状态 | 同步通常返回“处理中”，交易终态以异步返回为准 |
| resp_desc | 业务响应信息 | 关注失败原因 |
| bank_message | 通道返回描述 | 关注通道返回的失败原因 |
| hf_seq_id | 全局流水号 | 汇付系统生成全局流水号，后续可以用这个流水号查询交易 |
客户支付完成后汇付会将支付结果推送到客户异步地址，主要关注参数如下
| 参数 | 中文名 | 说明 |
|---|---|---|
| settlement_amt | 结算金额 | 用户实际支付金额。如有优惠该金额小于交易金额； |
| fee_amount | 手续费金额 | 斗拱扣收的支付手续费金额 |
| trans_stat | 交易状态 | 交易的最终结果；S：成功、F：失败 |
| out_trans_id | 用户账单上的交易订单号 | 交易在微信侧的流水号，参见用户账单说明 |
| party_order_id | 用户账单上的商户订单号 | 交易在微信侧生成的订单号；参见用户账单说明 |
| bank_message | 通道返回描述 | 如交易失败可以关注以下通道返回的错误描述 |
如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态；
3.3.2 退款流程
完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。参见扫码交易退款接口；
关注以下请参：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原交易请求日期 | Y | 用户发起支付的日期 |
| org_req_seq_id | 原交易请求流水号 | C | 商户系统发给斗拱的指令流水号 |
| org_hf_seq_id | 原交易全局流水号 | C | 汇付生成的系统流水号 |
| org_party_order_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列表
| 类型 | 功能 | 描述 |
|---|---|---|
| API | 聚合反扫 | 商户服务端调该接口传入pay_info完成最终交易; |
| 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
