實(shí)時(shí)分賬

最近更新時(shí)間：2023.8.11

1. 產(chǎn)品介紹

1.1 簡(jiǎn)介

分賬的應(yīng)用場(chǎng)景：可實(shí)現(xiàn)商戶或平臺(tái)向服務(wù)商、分銷(xiāo)商分賬，模式為商戶與下屬的用戶之間基于業(yè)務(wù)訂單收款的分賬。分賬有實(shí)時(shí)分賬與延時(shí)分賬（分賬+延遲能力的組合使用）兩種模式，您可以結(jié)合業(yè)務(wù)場(chǎng)景選擇實(shí)時(shí)或延時(shí)分賬。

分賬功能的實(shí)現(xiàn)主要通過(guò)接口與控臺(tái)兩種方式，控臺(tái)上操作比較適合大額低頻的分賬場(chǎng)景，對(duì)于小額高頻的交易建議您實(shí)時(shí)系統(tǒng)自動(dòng)分賬。

實(shí)時(shí)分賬

商戶收款交易完成即按照分賬規(guī)則給各個(gè)利益方完成分賬。

在交易過(guò)程中發(fā)起及完成，涉及交易類(lèi)型：聚合正掃、銀聯(lián)統(tǒng)一線上收銀臺(tái)支付、網(wǎng)銀支付、手機(jī)WAP支付、余額支付、快捷支付

對(duì)于實(shí)時(shí)分賬支持兩種分賬規(guī)則：

交易商戶開(kāi)通分賬權(quán)限時(shí)有兩種規(guī)則（通過(guò)rule_origin分賬規(guī)則來(lái)源參數(shù)指定）可根據(jù)商戶業(yè)務(wù)自行選擇：

01 接口發(fā)起：交易時(shí)指定acct_split_bunch分賬對(duì)象，指定參各分賬方以及各分賬方分賬金額（保留兩位小數(shù)）。

02 控臺(tái)配置：該規(guī)則是配置固定的分賬方、分賬比例單位%(0-100)，交易時(shí)無(wú)需指定分賬對(duì)象參數(shù)默認(rèn)讀取分賬權(quán)限開(kāi)通時(shí)配置的的分賬對(duì)象串來(lái)填充分賬對(duì)象，以配置對(duì)象來(lái)進(jìn)行分賬。

分賬業(yè)務(wù)包括以下功能：

• 服務(wù)商入駐：聯(lián)系匯付運(yùn)營(yíng)操作
• 服務(wù)商管理商戶：商戶入駐->商戶信息變更-業(yè)務(wù)信息變更-分賬配置：支持開(kāi)通或關(guān)閉分賬功能、支持分賬場(chǎng)景、支持資金模式、分賬手續(xù)費(fèi)僅支持實(shí)收、申請(qǐng)分賬最大比例、審核
• 商戶端功能使用：平臺(tái)商戶進(jìn)件->交易結(jié)算->商戶分賬：分賬模板配置、發(fā)起實(shí)時(shí)分賬、發(fā)起延時(shí)分賬、查詢(xún)分賬明細(xì)、分賬退款、分賬退款墊資、分賬手續(xù)費(fèi)->銀行大額轉(zhuǎn)賬->發(fā)起代發(fā)

業(yè)務(wù)流程圖：

1.2 應(yīng)用場(chǎng)景

• 分賬場(chǎng)景：電商、團(tuán)購(gòu)類(lèi)商戶用于分潤(rùn)、提成等；
• 分賬規(guī)則來(lái)源：接口動(dòng)態(tài)規(guī)則、控臺(tái)固定規(guī)則（接口規(guī)則優(yōu)先于控臺(tái)）；
• 分賬形式：
  • 商戶對(duì)平臺(tái)及多用戶（商戶收款資金分賬給平臺(tái)及平臺(tái)上的用戶）
  • 商戶對(duì)平臺(tái)（商戶收款資金只分給平臺(tái)）
  • 平臺(tái)對(duì)商戶及對(duì)用戶（平臺(tái)收款分賬給入駐在平臺(tái)上的商戶）
  • 其他（除以上場(chǎng)景外的模式，需單獨(dú)申請(qǐng)溝通）；

    

    

    當(dāng)選擇場(chǎng)景涉及線上，分賬模式為其他，此場(chǎng)景下還需要補(bǔ)充業(yè)務(wù)模式、資金流向、功能開(kāi)通用途說(shuō)明、與分賬方的合同等

    

    通過(guò)接口開(kāi)通

    實(shí)時(shí)分賬需要商戶通過(guò)分賬配置接口開(kāi)通分賬權(quán)限、最大分賬比例以及分賬手續(xù)費(fèi)配置。

    通過(guò)分賬配置接口進(jìn)行開(kāi)通分賬并配置；

    分賬配置接口入?yún)⑿桕P(guān)注acct_split_bunch_list字段：

    參數(shù)	中文名	必填	說(shuō)明
    rule_origin	分賬規(guī)則來(lái)源	Y	01 接口發(fā)起，02 控臺(tái)配置；示例值：01
    div_flag	分賬開(kāi)關(guān)	Y	Y：開(kāi)，N：關(guān)；示例值：Y
    apply_ratio	最大分賬比例	Y	0-100 的數(shù)值，支持兩位小數(shù)；示例值：20.00
    acct_split_bunch_list	分賬明細(xì)	N	jsonArray列表; 分賬規(guī)則來(lái)源選擇控臺(tái)配置(rule_origin=02)時(shí)必填

    參數(shù)	中文名	必填	說(shuō)明
    fee_rate	分賬比例	Y	百分比；數(shù)字類(lèi)型，大于0,保留2位小數(shù)；示例值：20.00
    huifu_id	匯付Id	Y	分賬接收方的匯付商戶號(hào)；示例值：6666000109812123

    2.1.3 分賬用戶開(kāi)通

    1、參與分賬的分賬接收方需要在匯付體系下開(kāi)通賬戶，通過(guò)用戶管理接口開(kāi)通并入駐用戶。

    用戶開(kāi)通

    根據(jù)商戶主體（有無(wú)營(yíng)業(yè)執(zhí)照）選擇企業(yè)、個(gè)人商戶基本信息開(kāi)戶接口進(jìn)行用戶開(kāi)戶；

    企業(yè)用戶基本信息開(kāi)戶API/個(gè)人用戶基本信息開(kāi)戶API

    創(chuàng)建用戶所需的相關(guān)資料

    1. 企業(yè)用戶：企業(yè)用戶資料：法人證件、營(yíng)業(yè)執(zhí)照、結(jié)算賬戶類(lèi)型（對(duì)公、對(duì)私）、結(jié)算卡、協(xié)議、聯(lián)系人手機(jī)號(hào)等；
    2. 個(gè)人用戶：個(gè)人用戶資料：身份證、營(yíng)業(yè)執(zhí)照、結(jié)算卡、協(xié)議、手機(jī)號(hào)等；

    用戶入駐

    用戶業(yè)務(wù)入駐接口給用戶進(jìn)行綁卡、結(jié)算/取現(xiàn)的權(quán)限、周期的配置以及費(fèi)率配置。

    用戶業(yè)務(wù)入駐API

    2、使用控臺(tái)創(chuàng)建用戶

    路徑：商戶控臺(tái)-【商戶管理】-【用戶創(chuàng)建】-選擇企業(yè)、個(gè)人商戶，填寫(xiě)基本信息、結(jié)算配置、取現(xiàn)配置、資料上傳。

    2.1.4分賬模板配置

    控臺(tái)分賬配置路徑：商戶控臺(tái)-【分賬管理】-【分賬模板配置】-【臺(tái)牌分賬規(guī)則】（實(shí)時(shí)）

    

    注意：對(duì)現(xiàn)有模板的任何操作都不會(huì)影響已按此模板分賬訂單。

    

    注：

    • 您的一筆業(yè)務(wù)收款的自留比例不能低于一個(gè)最低比例，系統(tǒng)會(huì)給出相應(yīng)提示。否則您的模板創(chuàng)建成功了，但應(yīng)用這個(gè)模板發(fā)起分賬時(shí)會(huì)被系統(tǒng)攔截。

    • 這個(gè)比例是您在申請(qǐng)開(kāi)通分賬業(yè)務(wù)時(shí)為您設(shè)置的。如果您的這個(gè)比例需要調(diào)整需要提交說(shuō)明材料，匯付審批之后才可以調(diào)整這個(gè)比例。

    2.1.5使用接口配置分賬

     接口開(kāi)通分賬：商戶分賬配置接口進(jìn)行分賬權(quán)限的開(kāi)通,分賬規(guī)則配置以及最大分賬比例的配置。

    最大分賬比例20以下是免審的，20以上需要審核，結(jié)果以異步方式通知。

    關(guān)注以下字段：

    參數(shù)	中文名	說(shuō)明
    rule_origin	分賬規(guī)則來(lái)源	選擇交易發(fā)生時(shí)默認(rèn)的分賬規(guī)則；01：接口發(fā)起，02：控臺(tái)配置；示例值：01
    div_flag	分賬開(kāi)關(guān)	Y：開(kāi)，N：關(guān)；示例值：Y
    apply_ratio	最大分賬比例	0-100 的數(shù)值，支持兩位小數(shù)；示例值：20.00

    交易實(shí)時(shí)分賬，例如聚合正掃接口交易，在分賬對(duì)象中傳入分賬對(duì)象，指定各分賬方分賬金額。各分賬方分賬金額之和要等于交易訂單金額。交易主體（收款方）必需也要在分賬對(duì)象中且原則上分賬金額不得低于手續(xù)費(fèi)金額，各分賬方分賬金額之和要等于支付訂單金額（分賬規(guī)則配置接口傳入時(shí)需要指定，若是配置的控臺(tái)配置規(guī)則無(wú)需指定分賬對(duì)象參數(shù)）。

    關(guān)注以下字段：

    參數(shù)	中文名	說(shuō)明
    acct_split_bunch	分賬對(duì)象	jsonObject字符串

    以交易異步通知或者交易查詢(xún)接口返回結(jié)果中的交易狀態(tài)成功即代表分賬成功，各分賬方可以通過(guò)余額查詢(xún)余額變化來(lái)確認(rèn)分賬是否到賬。

    2.2 對(duì)接準(zhǔn)備

    第一步：密鑰獲取

    聯(lián)調(diào)之前需要先獲取公私鑰，參見(jiàn)公私解鑰參數(shù)獲取說(shuō)明；

    第二步：公共參數(shù)獲取

    登錄服務(wù)商/商戶控臺(tái)后，可在開(kāi)發(fā)設(shè)置-開(kāi)發(fā)者信息中，獲取sys_id，product_id參數(shù)信息；

    

    3. 開(kāi)發(fā)指引

    3.1 對(duì)接規(guī)范

    調(diào)用匯付接口，均采取POST形式提交，數(shù)據(jù)格式統(tǒng)一為JSON格式，相關(guān)SDK及簽名方法見(jiàn)鏈接：

    SDK示例：Java SDK

    加簽驗(yàn)簽：v2版接口加簽驗(yàn)簽

    3.2 確認(rèn)業(yè)務(wù)配置

    控臺(tái)查詢(xún)分賬功能/延遲功能是否配置完成

    1. 通過(guò)服務(wù)商控臺(tái)-【代理商管理】-【代理商查看】-查看-業(yè)務(wù)信息

    

    2. 商戶控臺(tái)-【我的信息管理】-【我的信息】-業(yè)務(wù)信息查詢(xún)-分賬信息

    

    3. 通過(guò)商戶詳細(xì)信息查詢(xún)接口來(lái)確認(rèn)相關(guān)配置。

       3.3 系統(tǒng)調(diào)用流程

    3.3.1 交易流程

    以聚合正掃接口手續(xù)費(fèi)內(nèi)扣場(chǎng)景為例，其他交易類(lèi)型接口規(guī)則一樣：

    

    實(shí)時(shí)分賬交易：

    模式一：分賬規(guī)則配置是接口發(fā)起（rule_origin=01）時(shí)，商戶在發(fā)起支付時(shí)需指定分賬對(duì)象參數(shù)（acct_split_bunch），指定分賬方和分賬金額，如不傳分賬對(duì)象參數(shù)，則不分賬。

    模式二：分賬規(guī)則配置是控臺(tái)配置（rule_origin=02）時(shí)，無(wú)需指定分賬對(duì)象（接口傳分賬對(duì)象也不會(huì)生效），系統(tǒng)會(huì)按照分賬配置規(guī)則進(jìn)行分賬。

    商戶接收交易異步通知或通過(guò)掃碼交易查詢(xún)接口來(lái)獲取交易終態(tài)（trans_stat）和賬務(wù)狀態(tài)（acct_stat），交易成功即表示收款成功，交易和賬務(wù)狀態(tài)都成功即表示收款成功且分賬成功，資金已分賬到各分賬接收方賬戶了。

    注意：實(shí)時(shí)分賬指定分賬串時(shí)，交易收款主體商戶也必需在分賬對(duì)象中且原則上分賬金額不得低于手續(xù)費(fèi)金額，各分賬方分賬金額之和要等于支付訂單金額。

    3.3.2 分賬退款

    實(shí)時(shí)分賬退款

    僅支持接口退款，調(diào)用交易退款接口完成退款，支持分賬交易的部分退款和全額退款

    • 如果是全額退款無(wú)需指定分賬串，部分退款需要指定分賬對(duì)象參數(shù)（acct_split_bunch）指明各分賬參與方、參與方退款金額（金額不得大于分賬金額）。

    • 部分退款的退款手續(xù)費(fèi)按比例退還；

    3.3.3 查詢(xún)分賬明細(xì)

    控臺(tái)查詢(xún)：商戶控臺(tái)-【分賬管理】-【分賬明細(xì)】

    

    接口查詢(xún)：分賬明細(xì)查詢(xún)

    3.3.4 對(duì)賬流程

    為了滿足商戶財(cái)務(wù)的對(duì)賬需求，斗拱提供了對(duì)賬功能。

    方案一：控臺(tái)下載；

    

    方案二：接口獲取；參見(jiàn)交易結(jié)算對(duì)賬單查詢(xún)接口

    • 接口下載的對(duì)賬文件包括以下四類(lèi)：
      • 日對(duì)賬單類(lèi)型：包括日結(jié)算對(duì)賬單、日分賬對(duì)賬單、日出金對(duì)賬單；
      • 日交易數(shù)據(jù)：主要是各種支付交易記錄；
      • 月結(jié)算對(duì)賬單：按月匯總的結(jié)算對(duì)賬單；
      • 月交易數(shù)據(jù)：按月匯總支付交易記錄；

        3.3.5 異步通知

    針對(duì)交易結(jié)果，匯付會(huì)通過(guò)異步消息的方式通知客戶系統(tǒng)。 

    調(diào)用匯付接口時(shí)上送的異步通知地址為http/https路徑：服務(wù)器為POST回調(diào)，默認(rèn)超時(shí)時(shí)間為5秒，超時(shí)后會(huì)重試3次；不支持HTTP重定向；服務(wù)器對(duì)應(yīng)答不是200~300之間的錯(cuò)誤，會(huì)默認(rèn)重試3次；異步通知服務(wù)器對(duì)HTTPS不認(rèn)證驗(yàn)簽和ALLOW_ALL_HOSTNAME_VERIFIER；如商戶自定義通知端口，請(qǐng)使用8000-9005內(nèi)端口，否則無(wú)法通知；URL 上請(qǐng)勿附帶參數(shù)；異步回調(diào)請(qǐng)求編碼集為：UTF-8；收到通知后請(qǐng)返回狀態(tài)碼“200”,響應(yīng)異步通知。

    注意事項(xiàng)：

    同樣的異步消息可能會(huì)通知多次，因此接收異步消息的處理需做好冪等，保障多次接收到同樣的消息處理后結(jié)果不變。

    在實(shí)現(xiàn)異步消息接收的同時(shí)，都建議您在重要的業(yè)務(wù)環(huán)節(jié)，通過(guò)反查接口確認(rèn) 非終態(tài) 支付訂單的狀態(tài)，以保證在發(fā)生異步消息延遲或無(wú)法送達(dá)情況下的支付結(jié)果一致性。

    詳見(jiàn)異步通知使用說(shuō)明。

    4. API列表

    類(lèi)型	名稱(chēng)	描述
    API	商戶分賬配置接口	有分賬需求的商戶需要調(diào)用該接口開(kāi)通分賬權(quán)限
    API	商戶業(yè)務(wù)開(kāi)通接口	有延遲需求的商戶需要調(diào)用該接口開(kāi)通延遲權(quán)限
    API	商戶業(yè)務(wù)開(kāi)通修改接口	有延遲需求的商戶可調(diào)用該接口開(kāi)通延遲權(quán)限
    API	聚合正掃接口	交易收款
    API	交易確認(rèn)接口	對(duì)延遲交易做確認(rèn)并進(jìn)行分賬
    API	交易確認(rèn)查詢(xún)	對(duì)交易確認(rèn)訂單進(jìn)行查詢(xún)
    API	交易確認(rèn)退款接口	對(duì)確認(rèn)交易進(jìn)行退款
    API	交易確認(rèn)退款查詢(xún)	查詢(xún)交易確認(rèn)退款記錄
    API	交易退款接口	對(duì)原交易進(jìn)行退款
    API	分賬明細(xì)查詢(xún)	對(duì)分賬訂單進(jìn)行查詢(xún)
    API	企業(yè)用戶基本信息開(kāi)戶接口	給企業(yè)類(lèi)型用戶開(kāi)戶
    API	個(gè)人用戶基本信息開(kāi)戶接口	給個(gè)人類(lèi)型用戶開(kāi)戶
    API	用戶業(yè)務(wù)入駐接口	給用戶綁卡、配置結(jié)算、取現(xiàn)等

    5.常見(jiàn)問(wèn)題

    1. 實(shí)時(shí)分賬交易報(bào)錯(cuò)“主賬戶信息必須在分賬用戶信息中體現(xiàn)”。

    問(wèn)題原因：實(shí)時(shí)分賬，指定分賬對(duì)象時(shí)，交易主體商戶必須出現(xiàn)在分賬串內(nèi)。

    解決方法：分賬方商戶也要參與分賬，寫(xiě)到分賬對(duì)象中。

    2. 支付接口調(diào)用報(bào)錯(cuò)："resp_desc":"數(shù)據(jù)權(quán)限認(rèn)證失敗"

    問(wèn)題原因：商戶信息校驗(yàn)沒(méi)有通過(guò)。

    解決方案：

    1）檢查報(bào)文中的產(chǎn)品號(hào)（product_id）是否填寫(xiě)正確；

    2）檢查報(bào)文中的系統(tǒng)號(hào)（sys_id）和商戶號(hào)（huifu_Id） 從屬關(guān)系是否正確。

    3. 退款場(chǎng)景參考

    

    • 場(chǎng)景1、延遲分賬：未分賬+全額退款

    答：商戶A調(diào)取掃碼交易退款接口，不傳分賬串，交易金額傳100

    • 場(chǎng)景2、延遲分賬：未分賬+部分退款50元

    答：商戶A調(diào)取掃碼交易退款接口，傳入分賬串總和50，交易金額傳50

    • 場(chǎng)景3、延遲分賬：已分賬（部分分賬50元）+全額退款

    答：商戶A調(diào)取交易確認(rèn)退款接口，分賬串傳50，接口完成后，調(diào)取掃碼交易退款接口，不傳分賬串，交易金額傳100

    • 場(chǎng)景4、延遲分賬：已分賬（部分分賬50元）+部分退款

    答：1.部分退款30小于已分賬金額50，此時(shí)未分賬金額49.97

    方式1：商戶A調(diào)取掃碼交易退款接口:交易金額傳30，從未確認(rèn)余額出，其中匯付退款手續(xù)費(fèi)30/100*0.03=0.009 保留兩位小數(shù)向上取整為0.01，從未確認(rèn)資金出款30-0.01=29.99， 退款后待確認(rèn)金額為49.97-29.99=19.98。

    方式2：如果其中的資金涉及到被分賬方，首先調(diào)取交易確認(rèn)退款接口，分賬串傳30-30/100*0.03=29.99，然后調(diào)取掃碼交易退款接口:交易金額傳30。

    2.    部分退款60大于已分賬金額50，此時(shí)未分賬金額49.97.

    部分退款60，匯付退還手續(xù)費(fèi)金額為60/100*0.03=0.018 取0.02，從延遲戶出資60-0.02=59.98 。首先調(diào)取交易確認(rèn)退款接口，分賬串傳59.98-49.97=10.01元，然后調(diào)取掃碼交易退款接口:交易金額傳60.

    • 場(chǎng)景5、延遲分賬：已分賬（全部分賬）+全額退款

    答：商戶A調(diào)取交易確認(rèn)退款接口，不傳分賬串，接口完成后，調(diào)取掃碼交易退款接口，不傳分賬串，交易金額傳100

    • 場(chǎng)景6、延遲分賬：已分賬（全部分賬）+部分退款50元

    答：商戶A調(diào)取交易確認(rèn)退款接口，傳入分賬串（分賬串總額為49.98元，計(jì)算方法50/100*0.03 = 0.015元 ,然后向上取整取0.02元，50-0.02 = 49.98元），接口完成后，調(diào)取掃碼交易退款接口，不傳分賬串，交易金額傳50元

    • 場(chǎng)景7：實(shí)時(shí)分賬：部分退款50

    答：商戶A調(diào)取掃碼交易退款接口，傳入分賬串（分賬串總額50元），交易金額傳50元

    • 場(chǎng)景8：實(shí)時(shí)分賬：全部退款

    答：商戶A調(diào)取掃碼交易退款接口，不傳分賬串，交易金額傳100