實時分賬
最近更新時間：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
