预授权支付
最近更新时间：2023.7.24
1. 产品介绍
1.1 简介
预授权指预付款，商户估算了用户的消费金额之后，在用户账户、银行卡内冻结相应的金额，等用户消费完成后，商户再进行正式结算，相当于押金。常见的使用场景，如酒店、租赁、医美等行业。
预授权交易分为 4 个模块:预授权、预授权撤销、预授权完成、预授权完成撤销。
| 交易模块 | 说明 |
|---|---|
| 预授权 | 预授权交易，仅冻结用户资金 |
| 预授权撤销 | 预授权交易撤销 |
| 预授权完成 | 预授权交易完成 |
| 预授权完成撤销 | 预授权撤销交易完成 |
1.2 应用场景
- 汇付提供智能POS机，支持支付宝、微信、银行卡三种交易方式的预授权操作。
- 汇付提供API接口，支持支付宝、微信交易方式的预授权操作。
场景一：智能POS发起预授权演示
场景二：小程序、公众号、APP等调用API接口，发起预授权;
1.3 名词定义及说明
预授权：预付款，商户估算了用户的消费金额之后，在用户账户、银行卡内冻结相应的金额，等用户消费完成后，商户再进行正式结算，相当于押金
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，商户需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为商户发起入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，服务商需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为服务商发起入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
在斗拱完成商户进件入网
-
直签模式：已有汇付销售人员申请开通，商户无须另行操作；
-
服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息;
第三步：业务开通及配置
- 控台开通
- 汇付运营人员帮助渠道商开通预授权业务权限；进行支付宝支付、微信支付、银行卡支付-支付功能开通；
- 渠道商给商户开通预授权：
开通微信预授权：仅支持线下场景且行业为7011-住宿服务、7512-汽车出租、7296-服装出租
开通支付宝预授权：仅支持线下场景且行业为7011-住宿服务、7512-汽车出租、7296-服装出租
路径：渠道商控台-【商户管理】->【商户信息变更】
选择商户，操作-业务变更
配置修改：业务配置
风险控制模块：
是否开通刷卡预授权、是否开通支付宝预授权、是否开通微信预授权
- 接口开通
通过调用 商户业务开通 接口开通支付宝，微信预授权功能（刷卡预授权只能控台开通）
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
登录控台查询预授权是否配置完成
- 通过服务商控台-【商户管理】-【商户信息】-查询-业务配置
- 商户控台-【我的信息管理】-【我的信息】-业务信息
- 通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
适用对象：需要通过接口实现微信、支付宝预授权功能的商户。（POS终端的请参考终端指引文档）
小程序、公众号、APP等调用API接口进行微信支付宝预授权支付功能：预授权交易发起、预授权交易撤销、预授权交易完成、预授权交易撤销完成。
交易流程图：
交易步骤：
预授权交易入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| auth_code | 支付授权码 | Y | 扫码设备读出的条形码或者二维码信息； 示例值：2884138408701518074 |
| limit_pay_type | 禁用信用卡标记 | N | NO_CREDIT禁用信用卡，为空默认不禁用； 示例值：NO_CREDIT |
| notify_url | 异步通知地址 | N | 交易异步通知地址，http或https开头； 示例值：https://callback.service.com/xx |
预授权交易完成 入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原交易请求日期 | Y | 日期格式：yyyyMMdd |
| org_auth_no | 原授权号 | N | 原预授权交易请求流水号、原授权号、原预授权全局流水号三选一 |
| org_req_seq_id | 原预授权交易请求流水号 | N | 原预授权交易请求流水号、原授权号、原预授权全局流水号三选一 |
| pre_auth_hf_seq_id | 预授权汇付全局流水号 | N | 预授权汇付全局流水号 |
- 预授权交易以及交易完成查询，可通过扫码交易查询接口进行查询。
3.3.2 撤销流程
预授权交易撤销入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_auth_no | 原授权号 | N | orgReqSeqId,和authNo、preAuthHfSeqId三选一 |
| org_req_date | 原交易请求日期 | Y | 请求格式：yyyyMMdd |
| org_req_seq_id | 原交易请求流水号 | N | orgReqSeqId,和authNo、preAuthHfSeqId三选一 |
| pre_auth_hf_seq_id | 原预授权全局流水号 | N | orgReqSeqId,和authNo、preAuthHfSeqId三选一 |
预授权交易完成撤销 入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原预授权完成交易请求日期 | Y | 请求格式：yyyyMMdd |
| org_req_seq_id | 原预授权完成交易请求流水号 | N | 原预授权完成交易请求流水号 |
- 预授权交易撤销以及完成撤销查询，可通过扫码交易退款查询进行查询
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.常见问题
- 支付接口调用报错：“resp_desc”：“数据权限认证失败”
问题原因：商户信息校验没有通过。
解决方案：
1）检查报文中的产品号（product_id）是否填写正确;
2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。
更多问题详见斗拱开发者社区：https://service.dougong.net/t/qa
