实时分账
最近更新时间：2023.8.11
1. 产品介绍
1.1 简介
分账的应用场景：可实现商户或平台向服务商、分销商分账，模式为商户与下属的用户之间基于业务订单收款的分账。分账有实时分账与延时分账（分账+延迟能力的组合使用）两种模式，您可以结合业务场景选择实时或延时分账。
分账功能的实现主要通过接口与控台两种方式，控台上操作比较适合大额低频的分账场景，对于小额高频的交易建议您实时系统自动分账。
实时分账
商户收款交易完成即按照分账规则给各个利益方完成分账。
在交易过程中发起及完成，涉及交易类型：聚合正扫、银联统一线上收银台支付、网银支付、手机WAP支付、余额支付、快捷支付
对于实时分账支持两种分账规则：
交易商户开通分账权限时有两种规则（通过rule_origin分账规则来源参数指定）可根据商户业务自行选择：
01 接口发起：交易时指定acct_split_bunch分账对象，指定参各分账方以及各分账方分账金额（保留两位小数）。
02 控台配置：该规则是配置固定的分账方、分账比例单位%(0-100)，交易时无需指定分账对象参数默认读取分账权限开通时配置的的分账对象串来填充分账对象，以配置对象来进行分账。
分账业务包括以下功能：
- 服务商入驻：联系汇付运营操作
- 服务商管理商户：商户入驻->商户信息变更-业务信息变更-分账配置：支持开通或关闭分账功能、支持分账场景、支持资金模式、分账手续费仅支持实收、申请分账最大比例、审核
- 商户端功能使用：平台商户进件->交易结算->商户分账：分账模板配置、发起实时分账、发起延时分账、查询分账明细、分账退款、分账退款垫资、分账手续费->银行大额转账->发起代发
业务流程图：
1.2 应用场景
- 分账场景：电商、团购类商户用于分润、提成等；
- 分账规则来源：接口动态规则、控台固定规则（接口规则优先于控台）；
- 分账形式：
- 商户对平台及多用户（商户收款资金分账给平台及平台上的用户）
- 商户对平台（商户收款资金只分给平台）
- 平台对商户及对用户（平台收款分账给入驻在平台上的商户）
- 其他（除以上场景外的模式，需单独申请沟通）；
当选择场景涉及线上，分账模式为其他，此场景下还需要补充业务模式、资金流向、功能开通用途说明、与分账方的合同等
通过接口开通
实时分账需要商户通过分账配置接口开通分账权限、最大分账比例以及分账手续费配置。
通过分账配置接口进行开通分账并配置；
分账配置接口入参需关注acct_split_bunch_list字段：
参数 中文名 必填 说明 rule_origin 分账规则来源 Y 01 接口发起，02 控台配置；示例值：01 div_flag 分账开关 Y Y：开，N：关；示例值：Y apply_ratio 最大分账比例 Y 0-100 的数值，支持两位小数；示例值：20.00 acct_split_bunch_list 分账明细 N jsonArray列表; 分账规则来源选择控台配置(rule_origin=02)时必填 参数 中文名 必填 说明 fee_rate 分账比例 Y 百分比；数字类型，大于0,保留2位小数；示例值：20.00 huifu_id 汇付Id Y 分账接收方的汇付商户号；示例值：6666000109812123 2.1.3 分账用户开通
1、参与分账的分账接收方需要在汇付体系下开通账户，通过用户管理接口开通并入驻用户。
用户开通
根据商户主体（有无营业执照）选择企业、个人商户基本信息开户接口进行用户开户；
企业用户基本信息开户API/个人用户基本信息开户API
创建用户所需的相关资料
- 企业用户：企业用户资料：法人证件、营业执照、结算账户类型（对公、对私）、结算卡、协议、联系人手机号等；
- 个人用户：个人用户资料：身份证、营业执照、结算卡、协议、手机号等；
用户入驻
用户业务入驻接口给用户进行绑卡、结算/取现的权限、周期的配置以及费率配置。
用户业务入驻API
2、使用控台创建用户
路径：商户控台-【商户管理】-【用户创建】-选择企业、个人商户，填写基本信息、结算配置、取现配置、资料上传。
2.1.4分账模板配置
控台分账配置路径：商户控台-【分账管理】-【分账模板配置】-【台牌分账规则】（实时）
注意：对现有模板的任何操作都不会影响已按此模板分账订单。
注：
-
您的一笔业务收款的自留比例不能低于一个最低比例，系统会给出相应提示。否则您的模板创建成功了，但应用这个模板发起分账时会被系统拦截。
-
这个比例是您在申请开通分账业务时为您设置的。如果您的这个比例需要调整需要提交说明材料，汇付审批之后才可以调整这个比例。
2.1.5使用接口配置分账
接口开通分账：商户分账配置接口进行分账权限的开通,分账规则配置以及最大分账比例的配置。
最大分账比例20以下是免审的，20以上需要审核，结果以异步方式通知。
关注以下字段：
参数 中文名 说明 rule_origin 分账规则来源 选择交易发生时默认的分账规则；01：接口发起，02：控台配置；示例值：01 div_flag 分账开关 Y：开，N：关；示例值：Y apply_ratio 最大分账比例 0-100 的数值，支持两位小数；示例值：20.00 交易实时分账，例如聚合正扫接口交易，在分账对象中传入分账对象，指定各分账方分账金额。各分账方分账金额之和要等于交易订单金额。交易主体（收款方）必需也要在分账对象中且原则上分账金额不得低于手续费金额，各分账方分账金额之和要等于支付订单金额（分账规则配置接口传入时需要指定，若是配置的控台配置规则无需指定分账对象参数）。
关注以下字段：
参数 中文名 说明 acct_split_bunch 分账对象 jsonObject字符串 以交易异步通知或者交易查询接口返回结果中的交易状态成功即代表分账成功，各分账方可以通过余额查询余额变化来确认分账是否到账。
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息；
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
控台查询分账功能/延迟功能是否配置完成
- 通过服务商控台-【代理商管理】-【代理商查看】-查看-业务信息
- 商户控台-【我的信息管理】-【我的信息】-业务信息查询-分账信息
- 通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
以聚合正扫接口手续费内扣场景为例，其他交易类型接口规则一样：
实时分账交易：
模式一：分账规则配置是接口发起（rule_origin=01）时，商户在发起支付时需指定分账对象参数（acct_split_bunch），指定分账方和分账金额，如不传分账对象参数，则不分账。
模式二：分账规则配置是控台配置（rule_origin=02）时，无需指定分账对象（接口传分账对象也不会生效），系统会按照分账配置规则进行分账。
商户接收交易异步通知或通过扫码交易查询接口来获取交易终态（trans_stat）和账务状态（acct_stat），交易成功即表示收款成功，交易和账务状态都成功即表示收款成功且分账成功，资金已分账到各分账接收方账户了。
注意：实时分账指定分账串时，交易收款主体商户也必需在分账对象中且原则上分账金额不得低于手续费金额，各分账方分账金额之和要等于支付订单金额。
3.3.2 分账退款
实时分账退款
仅支持接口退款，调用交易退款接口完成退款，支持分账交易的部分退款和全额退款
-
如果是全额退款无需指定分账串，部分退款需要指定分账对象参数（acct_split_bunch）指明各分账参与方、参与方退款金额（金额不得大于分账金额）。
-
部分退款的退款手续费按比例退还；
3.3.3 查询分账明细
控台查询：商户控台-【分账管理】-【分账明细】
接口查询：分账明细查询
3.3.4 对账流程
为了满足商户财务的对账需求，斗拱提供了对账功能。
方案一：控台下载；
方案二：接口获取；参见交易结算对账单查询接口
- 接口下载的对账文件包括以下四类：
- 日对账单类型：包括日结算对账单、日分账对账单、日出金对账单；
- 日交易数据：主要是各种支付交易记录；
- 月结算对账单：按月汇总的结算对账单；
- 月交易数据：按月汇总支付交易记录；
3.3.5 异步通知
针对交易结果，汇付会通过异步消息的方式通知客户系统。
调用汇付接口时上送的异步通知地址为http/https路径：服务器为POST回调，默认超时时间为5秒，超时后会重试3次；不支持HTTP重定向；服务器对应答不是200~300之间的错误，会默认重试3次；异步通知服务器对HTTPS不认证验签和ALLOW_ALL_HOSTNAME_VERIFIER；如商户自定义通知端口，请使用8000-9005内端口，否则无法通知；URL 上请勿附带参数；异步回调请求编码集为：UTF-8；收到通知后请返回状态码“200”,响应异步通知。
注意事项：
同样的异步消息可能会通知多次，因此接收异步消息的处理需做好幂等，保障多次接收到同样的消息处理后结果不变。
在实现异步消息接收的同时，都建议您在重要的业务环节，通过反查接口确认 非终态 支付订单的状态，以保证在发生异步消息延迟或无法送达情况下的支付结果一致性。
详见异步通知使用说明。
4. API列表
类型 名称 描述 API 商户分账配置接口 有分账需求的商户需要调用该接口开通分账权限 API 商户业务开通接口 有延迟需求的商户需要调用该接口开通延迟权限 API 商户业务开通修改接口 有延迟需求的商户可调用该接口开通延迟权限 API 聚合正扫接口 交易收款 API 交易确认接口 对延迟交易做确认并进行分账 API 交易确认查询 对交易确认订单进行查询 API 交易确认退款接口 对确认交易进行退款 API 交易确认退款查询 查询交易确认退款记录 API 交易退款接口 对原交易进行退款 API 分账明细查询 对分账订单进行查询 API 企业用户基本信息开户接口 给企业类型用户开户 API 个人用户基本信息开户接口 给个人类型用户开户 API 用户业务入驻接口 给用户绑卡、配置结算、取现等 5.常见问题
- 实时分账交易报错“主账户信息必须在分账用户信息中体现”。
问题原因：实时分账，指定分账对象时，交易主体商户必须出现在分账串内。
解决方法：分账方商户也要参与分账，写到分账对象中。
- 支付接口调用报错："resp_desc":"数据权限认证失败"
问题原因：商户信息校验没有通过。
解决方案：
1）检查报文中的产品号（product_id）是否填写正确；
2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。
- 退款场景参考
- 场景1、延迟分账：未分账+全额退款
答：商户A调取扫码交易退款接口，不传分账串，交易金额传100
- 场景2、延迟分账：未分账+部分退款50元
答：商户A调取扫码交易退款接口，传入分账串总和50，交易金额传50
- 场景3、延迟分账：已分账（部分分账50元）+全额退款
答：商户A调取交易确认退款接口，分账串传50，接口完成后，调取扫码交易退款接口，不传分账串，交易金额传100
- 场景4、延迟分账：已分账（部分分账50元）+部分退款
答：1.部分退款30小于已分账金额50，此时未分账金额49.97
方式1：商户A调取扫码交易退款接口:交易金额传30，从未确认余额出，其中汇付退款手续费30/100*0.03=0.009 保留两位小数向上取整为0.01，从未确认资金出款30-0.01=29.99， 退款后待确认金额为49.97-29.99=19.98。
方式2：如果其中的资金涉及到被分账方，首先调取交易确认退款接口，分账串传30-30/100*0.03=29.99，然后调取扫码交易退款接口:交易金额传30。
2. 部分退款60大于已分账金额50，此时未分账金额49.97.
部分退款60，汇付退还手续费金额为60/100*0.03=0.018 取0.02，从延迟户出资60-0.02=59.98 。首先调取交易确认退款接口，分账串传59.98-49.97=10.01元，然后调取扫码交易退款接口:交易金额传60.
- 场景5、延迟分账：已分账（全部分账）+全额退款
答：商户A调取交易确认退款接口，不传分账串，接口完成后，调取扫码交易退款接口，不传分账串，交易金额传100
- 场景6、延迟分账：已分账（全部分账）+部分退款50元
答：商户A调取交易确认退款接口，传入分账串（分账串总额为49.98元，计算方法50/100*0.03 = 0.015元 ,然后向上取整取0.02元，50-0.02 = 49.98元），接口完成后，调取扫码交易退款接口，不传分账串，交易金额传50元
- 场景7：实时分账：部分退款50
答：商户A调取扫码交易退款接口，传入分账串（分账串总额50元），交易金额传50元
- 场景8：实时分账：全部退款
答：商户A调取扫码交易退款接口，不传分账串，交易金额传100
