From e418a4dfb135260e0e84d8f8ecda7ee7a4a18906 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Thu, 3 Sep 2026 20:06:28 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=8B=E8=B5=9B=E5=AD=A3=E9=80=9A=E8=A1=8C?= =?UTF-8?q?=E8=AF=81=E9=80=89=E9=A1=B9=20=E5=A2=9E=E5=8A=A0=E5=BC=80?= =?UTF-8?q?=E5=85=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/internal/modules/systemconfig/dto.go | 33 +- .../modules/systemconfig/publish_options.go | 13 +- docs/商家余额分账/0.商家余额分账-介绍.md | 347 ++++++++++++++++++ docs/商家余额分账/1.余额分账申请.md | 243 ++++++++++++ docs/商家余额分账/2. 余额分账结果查询.md | 224 +++++++++++ docs/商家余额分账/3.余额分账撤销.md | 224 +++++++++++ docs/商家余额分账/产品介绍.md | 163 ++++++++ .../admin/components/PublishOptionsDialog.vue | 7 + .../features/listings/api/listingOptions.ts | 3 + .../seller/composables/usePublishForm.ts | 6 +- .../views/MobileSellerListingCreateView.vue | 8 +- .../seller/views/SellerListingCreateView.vue | 3 +- 12 files changed, 1249 insertions(+), 25 deletions(-) create mode 100644 docs/商家余额分账/0.商家余额分账-介绍.md create mode 100644 docs/商家余额分账/1.余额分账申请.md create mode 100644 docs/商家余额分账/2. 余额分账结果查询.md create mode 100644 docs/商家余额分账/3.余额分账撤销.md create mode 100644 docs/商家余额分账/产品介绍.md diff --git a/backend/internal/modules/systemconfig/dto.go b/backend/internal/modules/systemconfig/dto.go index 88534e4..4211b3f 100644 --- a/backend/internal/modules/systemconfig/dto.go +++ b/backend/internal/modules/systemconfig/dto.go @@ -83,22 +83,23 @@ type HomeBannerItem struct { } type PublishOptionsDTO struct { - ServerOptions []string `json:"server_options"` - FaceOptions []string `json:"face_options"` - RankOptions []string `json:"rank_options"` - InsuranceOptions []string `json:"insurance_options"` - LevelOptions []string `json:"level_options"` - LoginMethodOptions []string `json:"login_method_options"` - RegionOptions []string `json:"region_options"` - SkinGroups []PublishOptionGroup `json:"skin_groups"` - QuantityItems []PublishQuantityItem `json:"quantity_items"` - ScreenshotSlots []PublishScreenshotSlot `json:"screenshot_slots"` - BanRecordOptions []string `json:"ban_record_options"` - BanEvidenceOptions []string `json:"ban_evidence_options"` - FireLevelMin int `json:"fire_level_min"` - PriceConfig PublishPriceConfig `json:"price_config"` - DepositRecommend PublishDepositRecommend `json:"deposit_recommend_config"` - RatioConfig PublishRatioConfig `json:"ratio_config"` + NextSeasonPassEnabled bool `json:"next_season_pass_enabled"` + ServerOptions []string `json:"server_options"` + FaceOptions []string `json:"face_options"` + RankOptions []string `json:"rank_options"` + InsuranceOptions []string `json:"insurance_options"` + LevelOptions []string `json:"level_options"` + LoginMethodOptions []string `json:"login_method_options"` + RegionOptions []string `json:"region_options"` + SkinGroups []PublishOptionGroup `json:"skin_groups"` + QuantityItems []PublishQuantityItem `json:"quantity_items"` + ScreenshotSlots []PublishScreenshotSlot `json:"screenshot_slots"` + BanRecordOptions []string `json:"ban_record_options"` + BanEvidenceOptions []string `json:"ban_evidence_options"` + FireLevelMin int `json:"fire_level_min"` + PriceConfig PublishPriceConfig `json:"price_config"` + DepositRecommend PublishDepositRecommend `json:"deposit_recommend_config"` + RatioConfig PublishRatioConfig `json:"ratio_config"` } type PublishOptionGroup struct { diff --git a/backend/internal/modules/systemconfig/publish_options.go b/backend/internal/modules/systemconfig/publish_options.go index fcc862d..4a5809f 100644 --- a/backend/internal/modules/systemconfig/publish_options.go +++ b/backend/internal/modules/systemconfig/publish_options.go @@ -14,12 +14,13 @@ func defaultPublishOptionsConfigValue() string { func DefaultPublishOptions() PublishOptionsDTO { return PublishOptionsDTO{ - ServerOptions: []string{"QQ", "微信", "Steam"}, - FaceOptions: []string{"是", "否"}, - RankOptions: []string{"青铜", "白银", "黄金", "铂金", "钻石", "黑鹰", "三角洲巅峰"}, - InsuranceOptions: []string{"2*1", "2*2", "2*3", "3*3"}, - LevelOptions: []string{"1级", "2级", "3级", "4级", "5级", "6级", "7级"}, - LoginMethodOptions: []string{"扫码", "账号密码"}, + NextSeasonPassEnabled: false, + ServerOptions: []string{"QQ", "微信", "Steam"}, + FaceOptions: []string{"是", "否"}, + RankOptions: []string{"青铜", "白银", "黄金", "铂金", "钻石", "黑鹰", "三角洲巅峰"}, + InsuranceOptions: []string{"2*1", "2*2", "2*3", "3*3"}, + LevelOptions: []string{"1级", "2级", "3级", "4级", "5级", "6级", "7级"}, + LoginMethodOptions: []string{"扫码", "账号密码"}, RegionOptions: []string{ "北京", "天津", "河北", "山西", "内蒙古", "辽宁", "吉林", "黑龙江", "上海", "江苏", "浙江", "安徽", "福建", "江西", "山东", "河南", diff --git a/docs/商家余额分账/0.商家余额分账-介绍.md b/docs/商家余额分账/0.商家余额分账-介绍.md new file mode 100644 index 0000000..95bf890 --- /dev/null +++ b/docs/商家余额分账/0.商家余额分账-介绍.md @@ -0,0 +1,347 @@ +# 一、功能简介 +乐刷的商家分账产品，提供多种方式商家发起分账，简单来看分为两种： + +1. 商家直接使用乐刷提供的商户PC后台发起分账； +2. 服务商接入乐刷的商家分账API，商家使用服务商提供的产品来发起分账。其中乐刷提供给服务商的分账API，有3种分账模式，服务商根据自身的分账业务特性和系统能力选择其一： + 1. 订单分账API。发起分账时，需要指明是对哪笔交易订单号发起分账。 + 2. 余额分账API。发起分账时，无需指明哪笔交易订单号分账，服务商根据自身的业务计算出需要分账的汇总资金，直接发起分账。 + 3. 自动分账API。服务商通过接口配置商家的分账规则，乐刷每日根据已设置的规则自动给商家发起分账。（该模式下，一般面向开发能力较弱的服务商，但服务商又需要商家登录由服务商提供的商家平台上操作场景） + +如服务商需要接入接口，若无特殊情况，建议服务商使用订单分账模式。 + +商家使用分账后，为了不混淆业务，一个商家仅可以使用以上三种分账模式中的一种，不可同时使用，且不能再使用乐刷提供的页面发起分账。 + +比如服务商已经接通余额分账的接口，并且给商家提供相应的分账操作页面，则不可以再让同一个商家直接使用乐刷提供的商家分账管理后台进行分账或者不可以让给同一个商家接通订单分账接口进行分账，该点需要服务商特别谨记。 + +以下介绍商家余额分账API产品的功能和操作步骤。 + +## 1. 余额分账功能简介 +商家余额分账功能，主要用于将商家交易成功后的二维码交易订单资金，按照一定的周期和比例，分账给与分账方（即收款商家）有合作关系的第三方，可以是收款商家的服务商、供货商、物流提供商、平台商等。 + +## 2. 余额分账功能使用场景 +(1) 物业租金抵扣 + +物业给商家提供场地收取商家的租金，为了减少经营商家的资金压力，通过商家的交易款抵扣铺租。由于铺租金额每月收取的金额固定且需要优先结清，无法分拆到具体交易订单订单，该类场景下可使用余额分账。 + +（2）设备押金收取 + +设备提供方给商家提供收款设备等产品，由于该类设备具有相应的成本，商家需要向设备商支付设备采购款，并采用先使用后通过支付的模式，该模式下，可通过余额分账进行分账，将前期的交易结算款用于支付设备款。 + +（3）其他合理的业务场景 + +商家的分账业务只要合理、合规，且可以合理的业务分账依据，并且分账的比例控制在合理范围或者分账金额控制在约定范围，也均可以使用该功能进行实现。 + +# 二、商家订单分账功能 +## 1. 接入准备 +（1）服务商完成服务商入网，取得**服务商编号**。 + +服务商入网流程详见： + +（2）服务商开发者获取到**服务商密钥**。 + +目前暂不支持服务商自行获取进件密钥，服务商密钥统一由乐刷的技术支持同学邮件发送给服务商的技术对接人。可在微信对接群联系乐刷的技术支持同事提供。 + +注： + +1）进件、交易、分账等接口使用的秘钥均为同一个秘钥。 + +2）乐刷当前仅支持向一级代理商提供密钥，不支持向二级及以下的代理商提供密钥。 + +3）商户秘钥不可以调用订单分账的接口，仅服务商秘钥（即1级代理商的秘钥）可调用。 + +（3）服务商、商户已完成订单分账功能的开通。 + +服务商、商户 开通分账功能的开通流程，详见：[三、分账开通流程](https://www.yuque.com/leshuazf/merchant_royalty/ynbk080r037yiicq) + +## 2. 接入指南 +### （1）简介 +完成 [接入准备](#tFfVI) 后，开发者可根据下方的接口调用流程快速接入能力。 + +### （2）分账流程 +#### 流程1：商户入网 +目前乐刷仅支持特定场景的商户使用余额分账，当前开放的特定场景为：医美、加油站、娱乐、教育培训。（若服务商有其他场景，需一事一议，提前与对应的销售沟通确认） + + + +目前乐刷提供两种方式供服务商完成商户入网： + +1） API接口：服务商通过接入乐刷提供的商户入网接口，在自有的产品和系统上增加相应的商户入网资料提交入口，完成分账方和分账接收方的入网。商户接口进件见：[商户入网指引](https://www.yuque.com/leshua-jhzf/qrcode_pay/gr9eco) + +注：分账接收方如无需走交易，则无需进行费率配置等操作。 + +2）代理商平台入网：乐刷为服务商提供服务商业务管理平台，包括服务商PC后台和服务商APP两种，服务商收集到商户的资金后，可登录该平台录入并提交资料完成商户入网。 + + + +商户入网需要提供的资料清单如下： + +1. 分账方： + 1. 小微商户：身份证、银行卡、三合照（门店照、店内照、收银台）。 + 2. 个体商户：营业执照、经营者身份证、银行卡、三合照（门店照、店内照、收银台）。 + 3. 企业商户：营业执照、法人身份证、结算银行卡（对私：结算人身份证、结算人银行卡、非法人结算授权书--非法人结算时提供，对公：开户许可证）、三合照（门店照、店内照、收银台）。 +2. 分账接收方（需要进行收单交易）： + 1. 小微商户：身份证、银行卡、三合照（门店照、店内照、收银台）。 + 2. 个体商户：营业执照、经营者身份证、银行卡、三合照（门店照、店内照、收银台）。 + 3. 企业商户：营业执照、法人身份证、结算银行卡（对私：结算人身份证、结算人银行卡、非法人结算授权书--非法人结算时提供，对公：开户许可证）、三合照（门店照、店内照、收银台）。 +3. 分账接收方（不需要进行收单交易）： + 1. 分账到对私账户。以小微商户入网至乐刷，生成对应的乐刷商户号。 + 1. 具体所需资料要求：身份证、银行卡、三合照（门店照、店内照、收银台）传以下专用图。 + + + + 2. 分账接收方进件时，简称命名为“商户名+分账”，如“张三分账” + 3. 用此套资料进件会被驳回，乐刷商户号不需要通过，只要生成乐刷商户号即可。此商户号无交易权限，不可发起交易，但不影响商户接收分账权限，不影响分账后的结算。 + 2. 分账到对公账户。以企业商户入网至乐刷。 + 1. 具体所需资料要求：营业执照、法人身份证、结算银行卡（对公：开户许可证）、三合照（门店照、店内照、收银台）。 + + + +#### 流程2：商家余额分账流程 +```mermaid +sequenceDiagram +participant A as 分账方(收款商家） +participant B as 分账接收方 +participant C as 服务商 +participant D as 乐刷 + +#--------以下为具体流程---------# +Note right of A:1.分账方开通商家分账 + A->>C: 申请使用分账功能 + alt 纸质协议开通模式 + C->>C:线下收集收款商家的纸质协议并拍照保存 + C->>D:调用“商户开通分账申请（线下协议）”接口/api/share-merchant/accredit + D-->>C:同步返回接口调用结果 + D->>D:乐刷风控人工审核（1-3工作日内）,审核通过即给收款商家开通分账 + C->>D:调用“商户开通分账结果查询”接口/api/share-merchant/accreditQuery + D-->>C:同步返回商户当前的审核结果 + + + else 电子协议开通模式 + C->>D:调用“商户开通分账申请（电子协议）”接口/api/share-merchant/elec-contract-accredit + D-->>C:同步返回调用结果及商家H5电子合同签署链接 + C->>A:将乐刷返回的H5电子合同发送给商家进行签署 + A->>D:商家法人在乐刷提供的H5上完成电子合同的签署 + D->>D:商家完成电子合同签署则自动开通分账 + C->>D:调用“商户开通分账结果查询”接口/api/share-merchant/accreditQuery + D-->>C:同步返回商户当前的分账开通结果 + + end + + +Note right of A:2.分账方和分账接收方绑定分账关系 + A->>C: 将分账接收方的名单提供给服务商 + C->>D:调用“分账关系绑定”接口/api/share-merchant/bind + D-->>C:同步返回绑定结果 + + A->>C: 申请终止某些分账接收方的分账 + C->>D:调用“分账关系解绑”接口/api/share-merchant/unbind + D-->>C:同步返回解绑结果 + + C->>D:调用“分账关系绑定查询”接口/api/share-merchant/queryBind + D-->>C:同步返回分账方已绑定对的分账接收方名单 + +Note right of A:3.收款商家进行交易 + A->>C: 申请发起收款（即正常的收款服务） + C->>D:调用“统一下单”接口get_tdcode或者“条码支付”接口upload_authcode，并传参royalty=1 + D-->>C:同步返回支付请求结果 + + C->>D:调用“交易查询”接口query_status查询支付结果 + D-->>C:同步返回交易订单的支付结果 + C->>A:告知/展示交易订单的支付结果 + + +Note right of A:4.分账发起 + A->>C: 申请发起分账（服务商和商户发起分账的流程可由服务商定义） + C->>D:调用“余额分账申请”接口/api/share-merchant/createSumAccredit + D-->>C:同步返回余额分账结果 + + C->>D:【可选】调用“余额分账结果查询”接口/api/share-merchant/querySumAccredit + D-->>C:同步返回订单分账结果 + + C->>D:【可选】调用“余额分账撤销”接口/api/share-merchant/canceSumAccredit，撤销某笔当日发起的余额分账 + D-->>C:同步返回余额分账撤销结果 + +Note right of A:5.分账资金结算出款 + + D->>D:D1日凌晨获取上一自然日发起的余额分账请求数据进行清分【3点为日切点】 + D->>A:D1日早上将分账给分账方的资金一笔结算给分账方 + D->>B:D1日早上将分账给分账接收方的资金一笔结算给分账接收方 + +Note right of A:6.分账对账 + D->>C:D1日早上将分账打款对账单放置乐刷的FTP，供服务商获取并进行对账 + + +``` + +### （3）流程说明 +#### 1）分账方和分账接收方入网 +分账方和分账接收方，均需要作为乐刷的商户户进行入网，获取到对应的乐刷商户号（乐刷商户号由10位数字组成） + +目前乐刷提供两种方式供服务商完成商户入网： + +1） API接口：服务商通过接入乐刷提供的商户入网接口，在自有的产品和系统上增加相应的商户入网资料提交入口，完成分账方和分账接收方的入网。商户接口进件见：[商户入网指引](https://www.yuque.com/leshua-jhzf/qrcode_pay/gr9eco) + +注：分账接收方如无需走交易，则无需进行费率配置等操作。 + +2）代理商平台入网：乐刷为服务商提供服务商业务管理平台，包括服务商PC后台和服务商APP两种，服务商收集到商户的资金后，可登录该平台录入并提交资料完成商户入网。 + +分账接收方如本身无交易的诉求，只需提交商户入网资料并完成商户入网审核即可，无需进行交易费率配置、微信认证等环节。 + +#### 2）分账方开通分账功能 +**① 分账协议签署和配置分账费率** + +分账方(即收款商家）要使用分账功能，需要先给分账方开通分账功能，目前乐刷提供API接口供服务商接入分账方开通分账功能，分账方要开通分账功能，必须与乐刷签署分账协议，明确分账比例、**分账费率**、服务商授权等内容，以保证分账业务的合规性，避免后续产生不必要的资金纠纷。 + +根据协议签署的方式不同，服务商可选择电子协议或者线下协议两种开通方式： + +1. 电子协议，服务商调用乐刷的“[商户开通分账申请（电子协议）](https://www.yuque.com/leshuazf/merchant_royalty/lkels6)”接口，提交分账方和签约比例、分账费率等信息后，乐刷返回相应的电子合同H5链接，服务商将电子合同链接通过自有平台展示、短信等方式给到商家，由商家法人完成验证和签署。 + +注：电子协议的签署只能由商家法人签署，不可由商家法人之外的其他人签署，在签署前，乐刷会通过校验手机号和银行卡是否为商家法人（即姓法人名、法人身份证号、手机号是否一致，或者法人姓名、法人身份证号、银行卡号是否一致）。 + +电子合同签署验证示例： + +（1）手机号验证模式： + + + + + +（2）银行卡验证模式： + + + +注：获取金额成功后，请商户查看自己的银行APP查看收到的打款金额，并在“回填金额”中输入收到的打款金额，并点击“下一步”完成验证。 + + + +2. 线下协议。服务商下载乐刷的线下协议模板，打印提供给商家，完成信息的填写后，盖上商户的公章（不可用个人按手印的方式，如采用该方式将会风控审核环节被驳回），然后调乐刷的“[商户开通分账申请（纸质协议）](https://www.yuque.com/leshuazf/merchant_royalty/mnslzx)”接口，提交商户开通分账申请。 + +商家分账线下协议模板见： + +[特约商户支付服务合作协议--商户分账补充协议.pdf](https://www.yuque.com/attachments/yuque/0/2022/pdf/529841/1658910656501-17b2fbc7-190b-4e9f-be44-c86afc80706a.pdf) + +服务商提交商家的分账开通申请后，后期可通过“[商户分账开通结果查询](https://www.yuque.com/leshuazf/merchant_royalty/vdbp7t)”接口，查询商家的分账开通结果。 + + + +**特别说明：** + +1. 服务商通过接口给分账方开通分账功能时，分账方的最大分账比例不可以超过服务商的分账比例。 +2. 商户的分账服务费率，需要高于服务商的分账成本，且不可高于5%。 +3. **若商户的分账比例或者分账费率需要变更，需要重新调接口进行协议签署，新的分账比例或者分账服务费率需要签署成功且审核通过后生效。** + + + +**② 余额分账开通报备** + +分账方通过接口的方式，提交分账协议后，会自动进入待审核的环节，进入待审核环节后，需要商家同步提供补充资料供乐刷审核方可完成商家余额分账的开通。资料的提交方式为邮件发送。具体要求如下： + +1. 需要提交的资料内容： + 1. 分账业务协议（商户与其分账接收方） + 2. 商户近一个月内的发票、收据（1-2张） + 3. 经营场景视频（需拍摄到清晰的营业执照） + 4. 特殊行业需额外提供对应的经营资质： + 1. 医疗、美容：《医疗机构执业许可证》 + 2. 医疗器械：《医疗器械经营企业许可证》 + 3. 药品：《药品经营许可证》 + 4. 加油站：《成品油批发经营批准证书》或《成品油仓储经营批准证书》或《成品油零售经营批准证书》或《燃气经营许可证》 + 5. 烟酒类：《烟草零售经营许可证》、《酒类经营许可证》 + 6. 物流/快递：《道路运输许可证》、《快递业务经营许可证》 +2. 邮件发送的要求： + 1. 标题：服务商编号_商户编号_商户全程_余额分账开通申请，如：2888568_0000000018_张三科技有限公司_余额分账开通申请 + 2. 发送人：乐刷商务对接人邮箱（具体请咨询对应的乐刷商务） + 3. 抄送人：carriezheng@yeahka.com;v_yoyodu@yeahka.com;rocketfu@yeahka.com;leshuasaas_spm@yeahka.com；support2@yeahka.com + 4. 邮件正文： + +我司服务商编号+服务商名称，现有“商户编号”+“商户全称”，欲使用乐刷提供的余额分账功能，以下为商家的真实业务场景说明： + +一、商家业务场景说明 + +二、商家分账协议（可作为附件提供） + +三、经营场景视频（可作为附件提供） + +四、特殊行业补充资料（可作为附件提供） + +五、近一个月内开设的发票照片（可作为附件提供） + +3. **乐刷审核** + +乐刷风控审核约需2-3个工作日，审核通过后会给商家开通余额分账的功能，并邮件回复发件人。 + +注：目前仅支持医美、娱乐、加油、教育培训行业的商家申请使用余额分账 + +#### 3）分账方和分账接收方建立绑定关系 +分账前需先通过“[分账关系绑定](https://www.yuque.com/leshuazf/merchant_royalty/ch4u7g)”接口，将分账接收方与分账方（即收款商家）建立绑定关系，一个分账方最多可绑定XXX个分账接收方（乐刷商户号维度）。 + + + +若分账方与某分账接收方终止业务合作，并且后续不需要继续向该分账接收方分账，可调用”[分账关系绑定](https://www.yuque.com/leshuazf/merchant_royalty/ixqa6n)”接口解除绑定关系。解除绑定关系后，后续不可以继续向该分账接收方发起分账。解除绑定关系后，可以继续调用“分账关系绑定”接口重新建立绑定关系。 + +服务商可调用”[分账关系绑定查询](https://www.yuque.com/leshuazf/merchant_royalty/yplfec)”接口查询分账方当前绑定的分账接收方名单。 + +#### 4）分账方进行交易 +当前仅支持对二维码交易的订单标记分账，不可对刷卡交易的订单标记分账。 + +需要分账的订单，交易下单时（统一下单接口和条码支付接口），可在下单接口中传入分账标识（royalty=1），将交易资金预先冻结在商户分账方的待分账账本中。 + +注：扣除交易手续费和分账手续费后，实时计入分账方的待分账账本。 + +#### 5）分账方分账余额分账 +分账交易订单交易成功后，该笔订单扣除交易收费和分账手续费后，剩余资金实时入账至分账方的待分账账本中，服务商可通过调用“[余额分账申请](https://www.yuque.com/leshuazf/merchant_royalty/ypx1g8)”接口发起分账请求。 + +分账请求提交后，乐刷会实时将分账方的待分账账本资金转出到分账接收方的待结算账户，并同步返回分账最终处理结果。 + + + +如某笔分账提交错误，可通过“[余额分账撤销](https://www.yuque.com/leshuazf/merchant_royalty/muqq15)”撤回当日（以0点作为日切点）发起的分账请求，撤销后的资金可用于退款或者继续发起分账。 + + + +服务商可通过调用“[余额分账结果查询](https://www.yuque.com/leshuazf/merchant_royalty/dqep7p)”接口，查询某笔余额分账的分账结果。 + +#### 6）分账方和分账方接收方的账资金结算出款 +服务商发起的订单分账，乐刷D1日凌晨进行统一的清分结算，并于D1早上7点左右出款至分账方和分账接收方。 + +结算出款环节无需服务商接入接口。 + +同一个分账接收方有多个分账方分给他时，会将合并一笔出款给到分账接收方。 + +某分账方既涉及自身给给自身，也涉及其他分账接收方分给自身时，所有的分账资金合并一笔出给该分账方。 + +分账方既涉及分账的交易，也涉及非分账的交易时，非分账的交易合并出款，并且不与分账的资金合并出款。 + +#### 7）商户分账数据对账 +乐刷每日早上8点左右，提供打款对账单给服务商进行对账。 + +[分账交易对账单](https://www.yuque.com/leshuazf/merchant_royalty/af71z3) + +[余额分账对账单](https://www.yuque.com/leshuazf/merchant_royalty/imflfs) + +[商家打款对账单](https://www.yuque.com/leshuazf/merchant_royalty/vi01zl) + +#### 8）服务商分润 +由于商户分账订单的出款具有延迟性，乐刷在交易成功后就对分账订单进行计费，因此分账交易订单成功后的次日，乐刷即计算服务商的分账分润（与交易分润分开入账）。 + +服务商可登录乐刷提供的代理商PC后台，在“分润提取”页面中提取分润。 + +注：分润的提取需要开立相应的发票 + +### （4）分账规则说明 +1. D1结算模式下（默认均采用该模式），分账资金为实付资金，交易手续费和分账手续费在入待分账账本前已经扣除，同一个分账接收方或者分账方，在同一周期内有多笔余额分账时，次日将合并一笔打款给商家。 +2. 一次分账请求，不可以超过50个分账接收方，且分账接收方不允许重复。 +3. 发起余额分账时，分账接收方和分账方的结算状态为正常，如有任一方的结算状态为冻结，则会导致分账失败 +4. 分账比例校验公式： （本次分账给分账接收方的分账金额 + 历史已成功分账给分账接收方的分账金额） ÷ （待分账账本总入账金额 － 分账订单历史成功退款金额 ） ≤ 商户分账比例 +5. 凌晨3点前发起的余额分账，可当日出款。举例：5日早上，对4日3:00-24:00和5日0:00-3:00 间发起的余额分账进行出款。 + +### （5）分账订单退款流程 +如服务商商需要对商户的分账订单进行退款，需要调用专门的“[分账交易退款](https://www.yuque.com/leshuazf/merchant_royalty/lo74w3)”接口发起退款。 + +目前仅支持90天内的交易发起退款，退款时，分账方的待分账账户需有足够的资金，若分账方的待分账账户中无足够资金，则无法进行退款。 + +## 3. 开发常见问题 + + + + + diff --git a/docs/商家余额分账/1.余额分账申请.md b/docs/商家余额分账/1.余额分账申请.md new file mode 100644 index 0000000..2c38ba9 --- /dev/null +++ b/docs/商家余额分账/1.余额分账申请.md @@ -0,0 +1,243 @@ +# 1. 接口用途 +该接口用于发起余额分账请求，交易成功后，交易订单的资金扣除交易手续费和分账手续费后，实时入账至分账方的待分账账本，如待分账账本余额足够，可发起余额分账。 + +接口发起的分账中，订单分账、余额分账、自动分账为不同的分账请求模式，同一个商户只允许选择其中的一种。 + +调用该接口前，商户需要开通分账功能，且商户的结算状态正常。 + +# 2. 接口说明 +## （1） 适用对象 + 1. 一级代理商 + +## （2）接口地址 +测试环境地址：无 + +乐刷不对测试环境的交易订单进行清分、入账和出款，请直接在生产环境进行调试。 + +生产环境地址：https://saas-mch.leshuazf.com/api/share-merchant/createSumAccredit + +## （3）测试参数 +无 + +## （4）特别说明 +1. D1结算模式下（默认均采用该模式），分账资金为实付资金，交易手续费和分账手续费在入待分账账本前已经扣除，同一个分账接收方或者分账方，在同一周期内有多笔余额分账时，次日将合并一笔打款给商家。 +2. 一次分账请求，不可以超过50个分账接收方，且分账接收方不允许重复。 +3. 发起余额分账时，分账接收方和分账方的结算状态为正常，如有任一方的结算状态为冻结，则会导致分账失败 +4. 分账比例校验公式： （本次分账给分账接收方的分账金额 + 历史已成功分账给分账接收方的分账金额） ÷ （待分账账本总入账金额 － 分账订单历史成功退款金额 ） ≤ 商户分账比例 +5. 凌晨3点前发起的余额分账，可当日出款。举例：5日早上，对4日3:00-24:00和5日0:00-3:00 间发起的余额分账进行出款。 + +## （5）频率限制 +40次/20秒 + +# 3. 接口请求 +## （1）请求方式 +1. 接口以 https的POST方式进行调用。 +2. 请求头部的 content-type 类型：application/x-www-form-urlencoded + +## （2）请求参数 +### 公共请求参数 +| **参数名称** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| **agentId** | String | M | 服务商编号，由乐刷分配的接入方唯一标识，明文传输。 | "2888568" | +| **version** | String | M | 目前固定值1.0 | "1.0" | +| **reqSerialNo** | String | M | 请求流水号(yyyyMMddHHmmssSSSXXXXX，其中 XXXXX为5位顺序号,禁止使用UUID等无意义数据) | "202207142012591234" | +| **sign** | String | M | 签名串，业务数据明文参与签名后经 Base64 编码的字符串。
签名方法详见[乐刷聚合签名](https://www.yuque.com/docs/share/a57e3853-70e6-445d-9193-e1892594b0ea?# 《聚合业务接口常规签名》) | "ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE" | +| **data** | String | M | 业务数据明文字符串（Json格式字符串，参照各个接口中输入参数说明） | '{\'cmd\': \'balance_allot_create\', \'merchant_id\': \'6763019848\', \'third_id\': \'202207151719300aNoeMhd\', \'amount\': \'1\', \'remark\': \'分账备注\', \'details\': \'[{"user_id":"6763019848","user_type":"2","amount":"1"}]\'}' | + + +### 业务请求参数 +| **参数** | **参数类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| cmd | String | M | 服务名称，本处固定为：balance_allot_create | "balance_allot_create" | +| merchant_id | String | M | 分账方的乐刷商户号 | "8613319257" | +| third_id | String | M | 商户分账单号 | "202207151719300aNoeMhd" | +| amount | String | M | 分账总金额
details中各分账接收方的分账金额汇总需等于本处的金额 | "2" | +| remark | String | O | 分账备注 | "备注说明1" | +| details | String | M | 分账详情，list格式并且需要转化为string，一次请求不可超过50个分账接收方且分账接收方不可重复，列表内字段说明：
1. user_id：分账接收方/分账方的乐刷商户编号
2. user_type：分账接收方类型，此处固定填2
3. amount：分账金额，单位为分 | '[{"user_id":"8613319257","user_type":"2","amount":"1"},{"user_id":"8123016461","user_type":"2","amount":"1"}]' | + + +## （3）请求示例 +```json +{'agentId': '2653276', 'version': '1.0', 'reqSerialNo': '20220805151053', 'sign': 'YWFiMWM5MjU4NDY3MzkwNGFiNjZjZTUwN2UxYjAzNzQ=', 'data': '{\'cmd\': \'balance_allot_create\', \'merchant_id\': \'6763019848\', \'third_id\': \'202207151719300aNoeMhd\', \'amount\': \'1\', \'remark\': \'分账备注\', \'details\': \'[{"user_id":"6763019848","user_type":"2","amount":"1"}]\'}'} + +``` + + + +```plain +https://saas-mch.leshuazf.com/api/share-merchant/createSumAccredit?agentId=2653276&version=1.0&reqSerialNo=20220805151053&sign=YWFiMWM5MjU4NDY3MzkwNGFiNjZjZTUwN2UxYjAzNzQ%3D&data=%7B%27cmd%27%3A+%27balance_allot_create%27%2C+%27merchant_id%27%3A+%276763019848%27%2C+%27third_id%27%3A+%27202207151719300aNoeMhd%27%2C+%27amount%27%3A+%271%27%2C+%27remark%27%3A+%27%E5%88%86%E8%B4%A6%E5%A4%87%E6%B3%A8%27%2C+%27details%27%3A+%27%5B%7B%22user_id%22%3A%226763019848%22%2C%22user_type%22%3A%222%22%2C%22amount%22%3A%221%22%7D%5D%27%7D + +``` + +```plain +curl --location --request POST 'http://t-saas-mch.lepass.cn/api/share-merchant/createSumAccredit' \ +--form 'agentId=2888568' \ +--form 'version=1.0' \ +--form 'reqSerialNo=20220715110526' \ +--form 'sign=ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE=' \ +--form 'data={"third_id":"0000000060402350","merchant_id":"9031015604", \ +"amount":"50","details":[{"user_id":"9031015604","user_type":"2","amount":"50"}]}' +``` + +# 4. 接口响应 +## （1）响应参数 +| **参数** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| respCode | String | M | 网关应答码。
000000，代表网关转发成功，具体的成功需要看retcode和status
其他应答码代表网关转发失败 | "000000" | +| respMsg | String | M | 网关应答说明，成功时返回“成功” | "成功" | +| version | String | M | 版本号 | "1.0" | +| reqSerialNo | String | M | 请求流水号 | "20220715122334" | +| data | Object | O | 业务参数
respCode=000000时返回 | {'third_id': '20220715173529LDxUoE9l', 'amount': '2', 'leshua_id': '2022071563329181703', 'details': '[{"user_id":"8613319257","user_type":"2","amount":"1"},{"user_id":"8123016461","user_type":"2","amount":"1"}]', 'remark': '分账备注', 'merchant_id': '8613319257', 'retmsg': 'success', 'retcode': '0', 'status': '1'}} | +| ┖retcode | String | M | 业务应答码,
0表示业务受理成功，分账成功需要看status
其他表示业务受理失败 | '0' | +| ┖retmsg | String | M | 业务应答说明
业务受理成功时返回“success” | 'success' | +| ┖third_id | String | O | 商户分账单号 | '20220715173529LDxUoE9l' | +| ┖amount | String | O | 分账总金额，单位为分 | "2" | +| ┖leshua_id | String | O | 乐刷分账单号 | "2022071563329181703" | +| ┖remark | String | O | 分账备注 | '分账备注' | +| ┖status | String | O | 分账状态，枚举如下：
0：处理中
1：分账成功
2：分账失败
3：分账撤销中
4：分账撤销成功
5：分账撤销失败
说明：分账成功后，资金次日统一出款 | '1' | +| ┖merchant_id | String | O | 分账方的乐刷商户号 | '8613319257' | +| ┖details | String[] | O | 分账详情，list格式并且转化为string，返回请求时送的details.
列表内字段说明：
1. user_id：分账接收方/分账方的乐刷商户编号
2. user_type：分账接收方类型，此处
3. amount：分账金额，单位为分 | '[{"user_id":"8613319257","user_type":"2","amount":"1"},{"user_id":"8123016461","user_type":"2","amount":"1"}]' | + + +## （2）响应示例（正常） +```json +{"version":"1.0","respCode":"000000","respMsg":"成功","reqSerialNo":"20220805151053","data":{"third_id":"202207151719300aNoeMhd","amount":"1","leshua_id":"2022080554653269903","details":"[{\"user_id\":\"6763019848\",\"user_type\":\"2\",\"amount\":\"1\"}]","remark":"分账备注","merchant_id":"6763019848","retmsg":"success","retcode":"0","status":"1"}} + +``` + +## （3）响应示例（异常） +```json +{'version': '1.0', 'respCode': '000037', 'respMsg': '分账商户未绑定', 'reqSerialNo': '20220715172759'} +``` + +# 5. 错误码 +**respCode 错误码** + +| **错误码（respCode）** | **错误描述（****respMsg****）** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| 000001 | 必填参数为空 | 乐刷聚合 | 标注为“M”的参数值为空 | 提供为“M”的参数值 | +| 000002 | 签名验证失败 | 乐刷聚合 | 请求方提供的sign参数值为错误的签名 | 1. 请确认服务商编号正确且已生成KEY 2. 请求方参照签名算法，修正sign参数值 | +| 000017 | 渠道商未开通此业务 | 乐刷聚合 | 当前服务商为开通该业务 服务商不属于一级服务商，暂未开通该业务 | 联系运营人员 | +| 000026 | 已暂停代理商进件 | 乐刷聚合 | 当前服务商进件商户权限已被关闭 | 联系运营人员 | +| 000027 | 商户已禁用分账功能 | 乐刷聚合 | 该商户分账权限已被关闭 | 联系运营人员 | +| 000004 | 接口调用频率限制 | 乐刷聚合 | 当前服务商调用接口过于频繁 | 降低接口调用频率 | +| 000005 | json格式或者数据类型不正确 | 乐刷聚合 | data 不是一个合法的json字符串或者字段类型不匹配 | 参照文档修正data值 | +| 000051 | 商户号不正确 | 乐刷聚合 | 商户号在乐刷不存在或者不属于该服务商 | 检查修正商户号 | + + +**respCode =000000时，业务错误码retcode如下：** + +| **错误码（retcode）** | **错误描述（****retmsg****）** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| -55001 | 分账请求中转失败 | 乐刷底层 | 可能调用上游失败 | 重试失败后联系乐刷运营 | +| -55002 | 不存在商户分账号 | 乐刷底层 | 商户号不存在或为空 | 检查商户号 | +| -55003 | 商户分账号重复 | 乐刷底层 | 多个分账商户号中有重复的商户号 | 检查商户号 | +| -55004 | 创建乐刷分账号失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55005 | 禁止分账 | 乐刷底层 | 商户被禁止分账 | 联系乐刷运营 | +| -55006 | 可分账余额小于等于零 | 乐刷底层 | 分账余额不足 | 检查是否已分账过，或重复分账， 或分账金额计算是否有误 | +| -55007 | 分账比例异常 | 乐刷底层 | 合同配置的分账比例非法 | 联系乐刷运营 | +| -55008 | 订单已分账或商户分账号重复 | 乐刷底层 | 订单已分账或商户分账号重复 | 检查分账订单是否已分账 | +| -55009 | 分账方数量限制 | 乐刷底层 | 分账方数量限制 | 检查分账方数量，不能超过50 | +| -55010 | 未查询到该订单，请检查后重试 | 乐刷底层 | 订单不存在 | 检查订单号 | +| -55011 | 不是分账订单 | 乐刷底层 | 订单不是分账订单，不能分账 | 检查订单号对应的订单类型 | +| -55012 | T0交易禁止分账 | 乐刷底层 | T0交易禁止分账 | T0交易禁止分账 | +| -55013 | 订单不支持退款 | 乐刷底层 | 订单不支持退款 | 订单不支持退款 | +| -55014 | 数据异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55015 | 获取订单号失败 | 乐刷底层 | 获取订单号失败 | 检查订单号是否存在 | +| -55016 | json解析异常 | 乐刷底层 | 参数格式异常 | 检查参数格式 | +| -55017 | 更新分账信息失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55018 | 创建分账信息失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55019 | 订单未分账 | 乐刷底层 | 订单未分账 | 检查订单分账状态 | +| -55020 | 查询分账信息失败 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55021 | 该订单已发起分账，请勿重复发起 | 乐刷底层 | 该订单已发起分账，请勿重复发起 | 勿重复发起 | +| -55022 | 分账异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55023 | 手续费承担方异常 | 乐刷底层 | 手续费承担方异常 | 检查手续费承担方参数 | +| -55024 | 该订单状态下不允许分账,请检查后重试 | 乐刷底层 | 该订单状态下不允许分账, 请检查后重试 | 检查订单状态 | +| -55025 | 分账金额有误，请检查后重试 | 乐刷底层 | 分账金额有误，请检查后重试 | 分账金额大于订单金额，或分账金额小于0等非法参数 | +| -55026 | 分账方异常 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55027 | 主体未配置分账比例 | 乐刷底层 | 主体未配置分账比例 | 检查分账主体的分账比例 | +| -55028 | 代理商或商户未开通分账权限 | 乐刷底层 | 代理商或商户未开通分账权限 | 联系乐刷运营 | +| -55029 | t0交易不允许分账 | 乐刷底层 | t0交易不允许分账 | t0交易不允许分账 | +| -55030 | 分账退款查询标记错误 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55031 | 分账次数异常 | 乐刷底层 | 分账次数异常 | 检查分账次数 | +| -55032 | 未分账金额不足以退款 | 乐刷底层 | 未分账金额不足以退款 | 检查退款金额 | +| -55033 | 接口不支持该功能 | 乐刷底层 | 接口不支持该功能 | 联系乐刷运营 | +| -55034 | 撤销失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55035 | 未查询到该分账订单，请检查后重试 | 乐刷底层 | 分账订单不存在 | 检查分账订单号 | +| -55036 | 数据库事务处理失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55037 | 分账订单处理中 | 乐刷底层 | 分账订单处理中 | 稍后重试 | +| -55038 | 分账订单号重复 | 乐刷底层 | 分账订单号重复 | 检查分账订单号后重试 | +| -55039 | 单次分账请求可分账金额必须等于分账金额 | 乐刷底层 | 单次分账请求可分账金额必须等于分账金额 | 检查分账金额 | +| -55040 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 乐刷底层 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 检查分账金额 | +| -55041 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 乐刷底层 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 检查分账商户信息 | +| -55042 | 可分账金额不足或订单已分账 | 乐刷底层 | 可分账金额不足或订单已分账 | 检查分账状态和已分账金额 | +| -55043 | 分账订单更新完成状态失败 | 乐刷底层 | 分账订单更新完成状态失败 | 重试失败后联系乐刷运营 | +| -55044 | 手续费承担次数异常 | 乐刷底层 | 手续费承担次数异常 | 检查商户是否承担了多次手续费 | +| -55045 | 分账查询历史库限流 | 乐刷底层 | 内部异常 | 稍后重试 | +| -55046 | 分账状态异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55047 | 生成结算侧分账服务请求异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55048 | 请求结算侧分账服务结果未知 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55049 | 结算侧分账服务异常返回失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55050 | 参数不合法 | 乐刷底层 | 参数不合法 | 检查参数中的必填、类型（特别是数字字符类型不能混用）等 | +| -55051 | 同一笔订单存在分账中，不允许继续分账 | 乐刷底层 | 同一笔订单存在分账中，不允许继续分账 | 有分账正在进行，请稍后重试 | +| -55052 | 不支持该分账退款模式 | 乐刷底层 | 不支持该分账退款模式 | 不支持该分账退款模式 | + + +# 6. 异步通知触发 +无 + +# 7.Demo示例 +```python +import requests +import hashlib +import base64 +import datetime +import json +##定义签名方法 +def sign_md5_base64(data,key): + signStr = "lepos" + key + data + m2 = hashlib.md5() + m2.update(signStr.encode('utf-8')) + md5str = m2.hexdigest() + base64Str = base64.b64encode(md5str.encode('utf-8')).decode() + return base64Str + +##定义流水号生成方法 +def reqSerialNo(): + now = datetime.datetime.now() + order_id = now.strftime("%Y-%m-%d-%H-%M-%S").replace("-", "") + return order_id + +##服务商参数 +agentId="" ## 这里填写服务商编号 +key="" ## 这里填写服务商密钥，与服务商进件和交易密钥一致 +request_url="https://saas-mch.leshuazf.com/api/share-merchant/createSumAccredit" ## 这里填写请求的接口地址 + +header={'Content-Type': 'application/x-www-form-urlencoded'} +##业务参数 +data={ + "cmd": "balance_allot_create", + "merchant_id": "6763019848", + "third_id": reqSerialNo(), + "amount": "1", + "remark": "分账备注", + "details": json.dumps([{"user_id":"6763019848","user_type":"2","amount":"1"}]) ##json.dumps() 是把python对象转换成json对象的一个过程，生成的是字符串 +} + +body = { + "agentId":agentId, + "version": "1.0", + "reqSerialNo": reqSerialNo(), + "sign": sign_md5_base64(json.dumps(data), key), + "data": json.dumps(data) +} + +req = requests.post(url=request_url, data=body,headers=header) + + +if req.status_code != 200: + print("Http请求失败，状态码：" + str(req.status_code) + "，错误信息：" + req.text) +else: + print(req.json()) + +``` diff --git a/docs/商家余额分账/2. 余额分账结果查询.md b/docs/商家余额分账/2. 余额分账结果查询.md new file mode 100644 index 0000000..6185e80 --- /dev/null +++ b/docs/商家余额分账/2. 余额分账结果查询.md @@ -0,0 +1,224 @@ +# 1. 接口用途 +该接口可查询发起的余额分账的结果。 + +# 2. 接口说明 +## （1）适用对象 + 1. 一级代理商 + +## （2）接口地址 +测试环境地址：无 + +生产环境地址：https://saas-mch.leshuazf.com/api/share-merchant/querySumAccredit + +## （3）测试参数 +无 + +## （4）特别说明 +## （5）频率限制 +40次/20秒 + +# 3. 接口请求 +## （1）请求方式 +1. 接口以 https的POST方式进行调用。 +2. 请求头部的 content-type 类型：application/x-www-form-urlencoded + +## （2）请求参数 +### 公共请求参数 +| **参数名称** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| **agentId** | String | M | 服务商编号，由乐刷分配的接入方唯一标识，明文传输。 | "2888568" | +| **version** | String | M | 目前固定值1.0 | "1.0" | +| **reqSerialNo** | String | M | 请求流水号(yyyyMMddHHmmssSSSXXXXX，其中 XXXXX为5位顺序号,禁止使用UUID等无意义数据) | "202207142012591234" | +| **sign** | String | M | 签名串，业务数据明文参与签名后经 Base64 编码的字符串。
签名方法详见[乐刷聚合签名](https://www.yuque.com/docs/share/a57e3853-70e6-445d-9193-e1892594b0ea?# 《聚合业务接口常规签名》) | "ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE" | +| **data** | String | M | 业务数据明文字符串（Json格式字符串，参照各个接口中输入参数说明） | '{"cmd": "balance_allot_query", "merchant_id": "6763019848", "third_id": "202207151719300aNoeMhd"}' | + + +### 业务请求参数 +| **参数** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | --- | --- | --- | +| cmd | String | M | 服务名称，本处固定为：balance_allot_query | "balance_allot_query" | +| merchant_id | String | M | 分账方的乐刷商户编号 | | +| third_id | String | M | 商户分账单号 | | + + +## （3）请求示例 +```json +{'agentId': '2653276', 'version': '1.0', 'reqSerialNo': '20220805151947', 'sign': 'MzBlNGUxNGFiMzg5NWYwZTVlNzcyNTQwNzIwNWQwMjc=', 'data': '{"cmd": "balance_allot_query", "merchant_id": "6763019848", "third_id": "202207151719300aNoeMhd"}'} + +``` + +```plain +curl --location --request POST 'http://t-saas-mch.lepass.cn/api/share-merchant/querySumAccredit' \ +--form 'agentId=2888568' \ +--form 'version=1.0' \ +--form 'reqSerialNo=20220715110526' \ +--form 'sign=ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE=' \ +--form 'data={"cmd":"balance_allot_query","third_id":"5856212145754114","merchant_id":"548957978"}' +``` + +```plain +https://saas-mch.leshuazf.com/api/share-merchant/querySumAccredit?agentId=2653276&version=1.0&reqSerialNo=20220805151947&sign=MzBlNGUxNGFiMzg5NWYwZTVlNzcyNTQwNzIwNWQwMjc%3D&data=%7B%22cmd%22%3A+%22balance_allot_query%22%2C+%22merchant_id%22%3A+%226763019848%22%2C+%22third_id%22%3A+%22202207151719300aNoeMhd%22%7D +``` + +# 4. 接口响应 +## （1）响应参数 +| **参数** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| respCode | String | M | 网关应答码。
000000，代表网关转发成功，具体的成功需要看retcode和status
其他应答码代表网关转发失败 | "000000" | +| respMsg | String | M | 网关应答说明，成功时返回“成功” | "成功" | +| version | String | M | 版本号 | "1.0" | +| reqSerialNo | String | M | 请求流水号 | "20220715122334" | +| data | Object | O | 分账详情，JSON格式
respCode=000000时返回 | | +| ┖retcode | String | M | 业务应答码,
0表示业务受理成功，分账成功需要看status
其他表示业务受理失败 | '0' | +| ┖retmsg | String | M | 业务应答说明
业务受理成功时返回“success” | 'success' | +| ┖merchant_id | String | O | 分账方的乐刷商户号
retcode=0时返回 | '8613319257' | +| ┖third_id | String | O | 商户分账单号
retcode=0时返回 | '20220715173529LDxUoE9l' | +| ┖leshua_id | String | O | 乐刷分账单号
retcode=0时返回 | "2022071563329181703" | +| ┖amount | String | O | 分账总金额，单位为分
retcode=0时返回 | "2" | +| ┖remark | String | O | 分账备注
retcode=0时返回 | '分账备注' | +| ┖status | String | O | 分账状态，枚举如下：
0：处理中
1：分账成功
2：分账失败
3：分账撤销中
4：分账撤销成功
5：分账撤销失败
说明：分账成功后，资金次日统一出款
retcode=0时返回 | '1' | +| ┖details | String[] | O | 分账详情，list格式，返回请求时送的details.
retcode=0时返回
列表内字段说明：
1. user_id：分账接收方/分账方的乐刷商户编号
2. user_type：分账接收方类型，此处
3. amount：分账金额，单位为分 | '[{"user_id":"8613319257","user_type":"2","amount":"1"},{"user_id":"8123016461","user_type":"2","amount":"1"}]' | + + +## （2）响应示例（正常） +```json +{'version': '1.0', 'respCode': '000000', 'respMsg': '成功', 'reqSerialNo': '20220715182702', 'data': {'third_id': '20220715173529LDxUoE9l', 'amount': '2', 'leshua_id': '2022071563329181703', 'details': '[{"amount":"1","user_id":"8123016461","user_type":"2"},{"amount":"1","user_id":"8613319257","user_type":"2"}]', 'remark': '分账备注', 'merchant_id': '8613319257', 'retmsg': 'success', 'retcode': '0', 'status': '1'}} +``` + +## （3）响应示例（异常） +```json +{'version': '1.0', 'respCode': '000103', 'respMsg': '汇总分账失败db_not_found', 'reqSerialNo': '20220715184903'} + +``` + +# 5. 错误码 +**respCode 错误码** + +| **错误码** | **错误描述** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| 000001 | 必填参数为空 | 乐刷聚合 | 标注为“M”的参数值为空 | 提供为“M”的参数值 | +| 000002 | 签名验证失败 | 乐刷聚合 | 请求方提供的sign参数值为错误的签名 | 1. 请确认服务商编号正确且已生成KEY 2 请求方参照签名算法，修正sign参数值 | +| 000017 | 渠道商未开通此业务 | 乐刷聚合 | 当前服务商为开通该业务 服务商不属于一级服务商，暂未开通该业务 | 联系运营人员 | +| 000026 | 已暂停代理商进件 | 乐刷聚合 | 当前服务商进件商户权限已被关闭 | 联系运营人员 | +| 000027 | 商户已禁用分账功能 | 乐刷聚合 | 该商户分账权限已被关闭 | 联系运营人员 | +| 000004 | 接口调用频率限制 | 乐刷聚合 | 当前服务商调用接口过于频繁 | 降低接口调用频率 | +| 000005 | json格式或者数据类型不正确 | 乐刷聚合 | data 不是一个合法的json字符串或者字段类型不匹配 | 参照文档修正data值 | +| 000051 | 商户号不正确 | 乐刷聚合 | 商户号在乐刷不存在或者不属于该服务商 | 检查修正商户号 | +| 000999 | 系统异常 | 乐刷聚合 | 系统升级或出现未知异常 | 紧急请联系乐刷运营 | +| 000063 | 商户未开通t1结算状态 | 乐刷聚合 | 分账接受放未开通T1结算 | 检查T1结算状态 | + + +**respCode =000000时，业务错误码retcode如下：** + +| **错误码（retcode）** | **错误描述（****retmsg****）** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| -55001 | 分账请求中转失败 | 乐刷底层 | 可能调用上游失败 | 重试失败后联系乐刷运营 | +| -55002 | 不存在商户分账号 | 乐刷底层 | 商户号不存在或为空 | 检查商户号 | +| -55003 | 商户分账号重复 | 乐刷底层 | 多个分账商户号中有重复的商户号 | 检查商户号 | +| -55004 | 创建乐刷分账号失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55005 | 禁止分账 | 乐刷底层 | 商户被禁止分账 | 联系乐刷运营 | +| -55006 | 可分账余额小于等于零 | 乐刷底层 | 分账余额不足 | 检查是否已分账过，或重复分账， 或分账金额计算是否有误 | +| -55007 | 分账比例异常 | 乐刷底层 | 合同配置的分账比例非法 | 联系乐刷运营 | +| -55008 | 订单已分账或商户分账号重复 | 乐刷底层 | 订单已分账或商户分账号重复 | 检查分账订单是否已分账 | +| -55009 | 分账方数量限制 | 乐刷底层 | 分账方数量限制 | 检查分账方数量，不能超过50 | +| -55010 | 未查询到该订单，请检查后重试 | 乐刷底层 | 订单不存在 | 检查订单号 | +| -55011 | 不是分账订单 | 乐刷底层 | 订单不是分账订单，不能分账 | 检查订单号对应的订单类型 | +| -55012 | T0交易禁止分账 | 乐刷底层 | T0交易禁止分账 | T0交易禁止分账 | +| -55013 | 订单不支持退款 | 乐刷底层 | 订单不支持退款 | 订单不支持退款 | +| -55014 | 数据异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55015 | 获取订单号失败 | 乐刷底层 | 获取订单号失败 | 检查订单号是否存在 | +| -55016 | json解析异常 | 乐刷底层 | 参数格式异常 | 检查参数格式 | +| -55017 | 更新分账信息失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55018 | 创建分账信息失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55019 | 订单未分账 | 乐刷底层 | 订单未分账 | 检查订单分账状态 | +| -55020 | 查询分账信息失败 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55021 | 该订单已发起分账，请勿重复发起 | 乐刷底层 | 该订单已发起分账，请勿重复发起 | 勿重复发起 | +| -55022 | 分账异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55023 | 手续费承担方异常 | 乐刷底层 | 手续费承担方异常 | 检查手续费承担方参数 | +| -55024 | 该订单状态下不允许分账,请检查后重试 | 乐刷底层 | 该订单状态下不允许分账, 请检查后重试 | 检查订单状态 | +| -55025 | 分账金额有误，请检查后重试 | 乐刷底层 | 分账金额有误，请检查后重试 | 分账金额大于订单金额，或分账金额小于0等非法参数 | +| -55026 | 分账方异常 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55027 | 主体未配置分账比例 | 乐刷底层 | 主体未配置分账比例 | 检查分账主体的分账比例 | +| -55028 | 代理商或商户未开通分账权限 | 乐刷底层 | 代理商或商户未开通分账权限 | 联系乐刷运营 | +| -55029 | t0交易不允许分账 | 乐刷底层 | t0交易不允许分账 | t0交易不允许分账 | +| -55030 | 分账退款查询标记错误 | 乐刷底层 | 内部异常 | 联系乐刷运营 | +| -55031 | 分账次数异常 | 乐刷底层 | 分账次数异常 | 检查分账次数 | +| -55032 | 未分账金额不足以退款 | 乐刷底层 | 未分账金额不足以退款 | 检查退款金额 | +| -55033 | 接口不支持该功能 | 乐刷底层 | 接口不支持该功能 | 联系乐刷运营 | +| -55034 | 撤销失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55035 | 未查询到该分账订单，请检查后重试 | 乐刷底层 | 分账订单不存在 | 检查分账订单号 | +| -55036 | 数据库事务处理失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55037 | 分账订单处理中 | 乐刷底层 | 分账订单处理中 | 稍后重试 | +| -55038 | 分账订单号重复 | 乐刷底层 | 分账订单号重复 | 检查分账订单号后重试 | +| -55039 | 单次分账请求可分账金额必须等于分账金额 | 乐刷底层 | 单次分账请求可分账金额必须等于分账金额 | 检查分账金额 | +| -55040 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 乐刷底层 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 检查分账金额 | +| -55041 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 乐刷底层 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 检查分账商户信息 | +| -55042 | 可分账金额不足或订单已分账 | 乐刷底层 | 可分账金额不足或订单已分账 | 检查分账状态和已分账金额 | +| -55043 | 分账订单更新完成状态失败 | 乐刷底层 | 分账订单更新完成状态失败 | 重试失败后联系乐刷运营 | +| -55044 | 手续费承担次数异常 | 乐刷底层 | 手续费承担次数异常 | 检查商户是否承担了多次手续费 | +| -55045 | 分账查询历史库限流 | 乐刷底层 | 内部异常 | 稍后重试 | +| -55046 | 分账状态异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55047 | 生成结算侧分账服务请求异常 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55048 | 请求结算侧分账服务结果未知 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55049 | 结算侧分账服务异常返回失败 | 乐刷底层 | 内部异常 | 重试失败后联系乐刷运营 | +| -55050 | 参数不合法 | 乐刷底层 | 参数不合法 | 检查参数中的必填、类型（特别是数字字符类型不能混用）等 | +| -55051 | 同一笔订单存在分账中，不允许继续分账 | 乐刷底层 | 同一笔订单存在分账中，不允许继续分账 | 有分账正在进行，请稍后重试 | +| -55052 | 不支持该分账退款模式 | 乐刷底层 | 不支持该分账退款模式 | 不支持该分账退款模式 | + + +# 6. 异步通知触发 +无 + +# 7.Demo示例 +```python +import requests +import hashlib +import base64 +import datetime +import json +##定义签名方法 +def sign_md5_base64(data,key): + signStr = "lepos" + key + data + m2 = hashlib.md5() + m2.update(signStr.encode('utf-8')) + md5str = m2.hexdigest() + base64Str = base64.b64encode(md5str.encode('utf-8')).decode() + return base64Str + +##定义流水号生成方法 +def reqSerialNo(): + now = datetime.datetime.now() + order_id = now.strftime("%Y-%m-%d-%H-%M-%S").replace("-", "") + return order_id + +##服务商参数 +agentId="" ## 这里填写服务商编号 +key="" ## 这里填写服务商密钥，与服务商进件和交易密钥一致 +request_url="https://saas-mch.leshuazf.com/api/share-merchant/querySumAccredit" ## 这里填写请求的接口地址 + +header={'Content-Type': 'application/x-www-form-urlencoded'} +##业务参数 +data={ + "cmd": "balance_allot_query", + "merchant_id": "6763019848", + "third_id": "202207151719300aNoeMhd"} + +body = { + "agentId":agentId, + "version": "1.0", + "reqSerialNo": reqSerialNo(), + "sign": sign_md5_base64(json.dumps(data), key), + "data": json.dumps(data) +} + +req = requests.post(url=request_url, data=body,headers=header) + + +if req.status_code != 200: + print("Http请求失败，状态码：" + str(req.status_code) + "，错误信息：" + req.text) +else: + print(req.text) + +``` + + diff --git a/docs/商家余额分账/3.余额分账撤销.md b/docs/商家余额分账/3.余额分账撤销.md new file mode 100644 index 0000000..73a76a8 --- /dev/null +++ b/docs/商家余额分账/3.余额分账撤销.md @@ -0,0 +1,224 @@ +# 1. 接口用途 +该接口可撤销已发起的余额分账。 + +# 2. 接口说明 +## （1） 适用对象 + 1. 一级代理商 + +## （2）接口地址 +测试环境地址：无 + +生产环境地址：https://saas-mch.leshuazf.com/api/share-merchant/canceSumAccredit + +## （3）测试参数 +无 + +## （4）特别说明 +1. 分账单号撤销后，不可再继续撤销，可通过查询接口查询该笔订单的当前状态。 +2. 跨日后，由于已经步入结算环节，不支持再进行撤销。 + +## （5）频率限制 +40次/20秒 + +# 3. 接口请求 +## （1）请求方式 +1. 接口以 https的POST方式进行调用。 +2. 请求头部的 content-type 类型：application/x-www-form-urlencoded + +## （2）请求参数 +### 公共请求参数 +| **参数名称** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| **agentId** | String | M | 服务商编号，由乐刷分配的接入方唯一标识，明文传输。 | "2888568" | +| **version** | String | M | 目前固定值1.0 | "1.0" | +| **reqSerialNo** | String | M | 请求流水号(yyyyMMddHHmmssSSSXXXXX，其中 XXXXX为5位顺序号,禁止使用UUID等无意义数据) | "202207142012591234" | +| **sign** | String | M | 签名串，业务数据明文参与签名后经 Base64 编码的字符串。
签名方法详见[乐刷聚合签名](https://www.yuque.com/docs/share/a57e3853-70e6-445d-9193-e1892594b0ea?# 《聚合业务接口常规签名》) | "ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE" | +| **data** | String | M | 业务数据明文字符串（Json格式字符串，参照各个接口中输入参数说明） | '{"cmd": "balance_allot_cancel", "merchant_id": "6763019848", "third_id": "202207151719300aNoeMhd"}' | + + +### 业务请求参数 +| **参数** | **参数类型** | **必填** | **长度** | **说明** | **示例** | +| --- | --- | --- | --- | --- | --- | +| cmd | String | M | | 服务名称，本处固定为：balance_allot_cancel | "balance_allot_cancel" | +| merchant_id | String | M | | 分账方的乐刷商户编号 | "8613319257" | +| third_id | String | M | | 商户分账单号 | "20220715173529LDxUoE9l" | + + +## （3）请求示例 +```json +{'agentId': '2653276', 'version': '1.0', 'reqSerialNo': '20220805152236', 'sign': 'ZDE2MzU0NjQ5MDE5MTdkYTYzZTExMTYyYzgxZjdlNzM=', 'data': '{"cmd": "balance_allot_cancel", "merchant_id": "6763019848", "third_id": "202207151719300aNoeMhd"}'} +``` + +```plain +curl --location --request POST 'http://t-saas-mch.lepass.cn/api/share-merchant/canceSumAccredit' \ +--form 'agentId=2888568' \ +--form 'version=1.0' \ +--form 'reqSerialNo=20220715110526' \ +--form 'sign=ZTNlZTUyZTA5MDE5YzQxZWViMWRhYjEwODhhN2EwOTE=' \ +--form 'data={"third_id":"5856212145754114","cmd":"balance_allot_cancel","merchant_id":"0000000017"}' +``` + +```plain +https://saas-mch.leshuazf.com/api/share-merchant/canceSumAccredit?agentId=2653276&version=1.0&reqSerialNo=20220805152236&sign=ZDE2MzU0NjQ5MDE5MTdkYTYzZTExMTYyYzgxZjdlNzM%3D&data=%7B%22cmd%22%3A+%22balance_allot_cancel%22%2C+%22merchant_id%22%3A+%226763019848%22%2C+%22third_id%22%3A+%22202207151719300aNoeMhd%22%7D +``` + +# 4. 接口响应 +## （1）响应参数 +| **参数** | **类型** | **必填** | **说明** | **示例** | +| --- | --- | :---: | --- | --- | +| respCode | String | M | 应答码。
000000，代表分账关系解绑成功
其他应答码代表分账关系解绑失败 | "000000" | +| respMsg | String | M | 应答说明，成功时返回“成功” | "成功" | +| version | String | M | 版本号 | "1.0" | +| reqSerialNo | String | M | 请求流水号 | "20220715122334" | +| data | Object | O | 业务参数
respCode=000000时返回 | {'third_id': '20220715173529LDxUoE9l', 'leshua_id': '2022071563329181703', 'merchant_id': '8613319257', 'retmsg': 'success', 'retcode': '0', 'status': '4'}} | +| ┖retcode | String | M | 业务应答码,
0表示业务受理成功，分账成功需要看status
其他表示业务受理失败 | '0' | +| ┖retmsg | String | M | 业务应答说明
业务受理成功时返回“success” | 'success' | +| ┖third_id | String | O | 商户分账单号
retcode=0时返回 | '20220715173529LDxUoE9l' | +| ┖leshua_id | String | O | 乐刷分账单号
retcode=0时返回 | "2022071563329181703" | +| ┖merchant_id | String | O | 分账方的乐刷商户号
retcode=0时返回 | '8613319257' | +| ┖status | String | O | 分账状态，枚举如下：
0：处理中
1：分账成功
2：分账失败
3：分账撤销中
4：分账撤销成功
5：分账撤销失败
说明：分账成功后，资金次日统一出款
retcode=0时返回 | '1' | + + +## （2）响应示例（正常） +```json +{'version': '1.0', 'respCode': '000000', 'respMsg': '成功', 'reqSerialNo': '20220715185901', 'data': {'third_id': '20220715173529LDxUoE9l', 'leshua_id': '2022071563329181703', 'merchant_id': '8613319257', 'retmsg': 'success', 'retcode': '0', 'status': '4'}} + +``` + +## （3）响应示例（异常） +```json +{'version': '1.0', 'respCode': '000103', 'respMsg': '汇总分账失败status_not_allow', 'reqSerialNo': '20220715190421'} +``` + +# 5. 错误码 +**respCode 错误码** + +| **错误码** | **错误描述** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| 000001 | 必填参数为空 | 乐刷 | 标注为“M”的参数值为空 | 提供为“M”的参数值 | +| 000002 | 签名验证失败 | 乐刷 | 请求方提供的sign参数值为错误的签名 | 1. 请确认服务商编号正确且已生成KEY 1. 请求方参照签名算法，修正sign参数值 | +| 000017 | 渠道商未开通此业务 | 乐刷 | 当前服务商为开通该业务 服务商不属于一级服务商，暂未开通该业务 | 联系运营人员 | +| 000026 | 已暂停代理商进件 | 乐刷 | 当前服务商进件商户权限已被关闭 | 联系运营人员 | +| 000027 | 商户已禁用分账功能 | 乐刷 | 该商户分账权限已被关闭 | 联系运营人员 | +| 000004 | 接口调用频率限制 | 乐刷 | 当前服务商调用接口过于频繁 | 降低接口调用频率 | +| 000005 | json格式或者数据类型不正确 | 乐刷 | data 不是一个合法的json字符串或者字段类型不匹配 | 参照文档修正data值 | +| 000051 | 商户号不正确 | 乐刷 | 商户号在乐刷不存在或者不属于该服务商 | 检查修正商户号 | +| 000999 | 系统异常 | 乐刷 | 系统升级或出现未知异常 | 紧急请联系乐刷运营 | +| 000063 | 商户未开通t1结算状态 | 乐刷 | 分账接受放未开通T1结算 | 检查T1结算状态 | + + +**respCode =000000时，业务错误码retcode如下：** + +| **错误码（retcode）** | **错误描述（****retmsg****）** | **错误来源** | **异常原因** | **解决方案** | +| --- | --- | --- | --- | --- | +| -55001 | 分账请求中转失败 | 结算 | 可能调用上游失败 | 重试失败后联系乐刷运营 | +| -55002 | 不存在商户分账号 | 结算 | 商户号不存在或为空 | 检查商户号 | +| -55003 | 商户分账号重复 | 结算 | 多个分账商户号中有重复的商户号 | 检查商户号 | +| -55004 | 创建乐刷分账号失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55005 | 禁止分账 | 结算 | 商户被禁止分账 | 联系乐刷运营 | +| -55006 | 可分账余额小于等于零 | 结算 | 分账余额不足 | 检查是否已分账过，或重复分账， 或分账金额计算是否有误 | +| -55007 | 分账比例异常 | 结算 | 合同配置的分账比例非法 | 联系乐刷运营 | +| -55008 | 订单已分账或商户分账号重复 | 结算 | 订单已分账或商户分账号重复 | 检查分账订单是否已分账 | +| -55009 | 分账方数量限制 | 结算 | 分账方数量限制 | 检查分账方数量，不能超过50 | +| -55010 | 未查询到该订单，请检查后重试 | 结算 | 订单不存在 | 检查订单号 | +| -55011 | 不是分账订单 | 结算 | 订单不是分账订单，不能分账 | 检查订单号对应的订单类型 | +| -55012 | T0交易禁止分账 | 结算 | T0交易禁止分账 | T0交易禁止分账 | +| -55013 | 订单不支持退款 | 结算 | 订单不支持退款 | 订单不支持退款 | +| -55014 | 数据异常 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55015 | 获取订单号失败 | 结算 | 获取订单号失败 | 检查订单号是否存在 | +| -55016 | json解析异常 | 结算 | 参数格式异常 | 检查参数格式 | +| -55017 | 更新分账信息失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55018 | 创建分账信息失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55019 | 订单未分账 | 结算 | 订单未分账 | 检查订单分账状态 | +| -55020 | 查询分账信息失败 | 结算 | 内部异常 | 联系乐刷运营 | +| -55021 | 该订单已发起分账，请勿重复发起 | 结算 | 该订单已发起分账，请勿重复发起 | 勿重复发起 | +| -55022 | 分账异常 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55023 | 手续费承担方异常 | 结算 | 手续费承担方异常 | 检查手续费承担方参数 | +| -55024 | 该订单状态下不允许分账,请检查后重试 | 结算 | 该订单状态下不允许分账, 请检查后重试 | 检查订单状态 | +| -55025 | 分账金额有误，请检查后重试 | 结算 | 分账金额有误，请检查后重试 | 分账金额大于订单金额，或分账金额小于0等非法参数 | +| -55026 | 分账方异常 | 结算 | 内部异常 | 联系乐刷运营 | +| -55027 | 主体未配置分账比例 | 结算 | 主体未配置分账比例 | 检查分账主体的分账比例 | +| -55028 | 代理商或商户未开通分账权限 | 结算 | 代理商或商户未开通分账权限 | 联系乐刷运营 | +| -55029 | t0交易不允许分账 | 结算 | t0交易不允许分账 | t0交易不允许分账 | +| -55030 | 分账退款查询标记错误 | 结算 | 内部异常 | 联系乐刷运营 | +| -55031 | 分账次数异常 | 结算 | 分账次数异常 | 检查分账次数 | +| -55032 | 未分账金额不足以退款 | 结算 | 未分账金额不足以退款 | 检查退款金额 | +| -55033 | 接口不支持该功能 | 结算 | 接口不支持该功能 | 联系乐刷运营 | +| -55034 | 撤销失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55035 | 未查询到该分账订单，请检查后重试 | 结算 | 分账订单不存在 | 检查分账订单号 | +| -55036 | 数据库事务处理失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55037 | 分账订单处理中 | 结算 | 分账订单处理中 | 稍后重试 | +| -55038 | 分账订单号重复 | 结算 | 分账订单号重复 | 检查分账订单号后重试 | +| -55039 | 单次分账请求可分账金额必须等于分账金额 | 结算 | 单次分账请求可分账金额必须等于分账金额 | 检查分账金额 | +| -55040 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 结算 | 多次分账，最后一次分账，分账的金额必须是剩余的所有可分账金额 | 检查分账金额 | +| -55041 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 结算 | 多次分账，最后一次分账，分账对象必须有交易主体商户 | 检查分账商户信息 | +| -55042 | 可分账金额不足或订单已分账 | 结算 | 可分账金额不足或订单已分账 | 检查分账状态和已分账金额 | +| -55043 | 分账订单更新完成状态失败 | 结算 | 分账订单更新完成状态失败 | 重试失败后联系乐刷运营 | +| -55044 | 手续费承担次数异常 | 结算 | 手续费承担次数异常 | 检查商户是否承担了多次手续费 | +| -55045 | 分账查询历史库限流 | 结算 | 内部异常 | 稍后重试 | +| -55046 | 分账状态异常 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55047 | 生成结算侧分账服务请求异常 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55048 | 请求结算侧分账服务结果未知 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55049 | 结算侧分账服务异常返回失败 | 结算 | 内部异常 | 重试失败后联系乐刷运营 | +| -55050 | 参数不合法 | 结算 | 参数不合法 | 检查参数中的必填、类型（特别是数字字符类型不能混用）等 | +| -55051 | 同一笔订单存在分账中，不允许继续分账 | 结算 | 同一笔订单存在分账中，不允许继续分账 | 有分账正在进行，请稍后重试 | +| -55052 | 不支持该分账退款模式 | 结算 | 不支持该分账退款模式 | 不支持该分账退款模式 | + + + + +# 6. 异步通知触发 +无 + +# 7.Demo示例 +```python +import requests +import hashlib +import base64 +import datetime +import json +##定义签名方法 +def sign_md5_base64(data,key): + signStr = "lepos" + key + data + m2 = hashlib.md5() + m2.update(signStr.encode('utf-8')) + md5str = m2.hexdigest() + base64Str = base64.b64encode(md5str.encode('utf-8')).decode() + return base64Str + +##定义流水号生成方法 +def reqSerialNo(): + now = datetime.datetime.now() + order_id = now.strftime("%Y-%m-%d-%H-%M-%S").replace("-", "") + return order_id + +##服务商参数 +agentId="" ## 这里填写服务商编号 +key="" ## 这里填写服务商密钥，与服务商进件和交易密钥一致 +request_url="https://saas-mch.leshuazf.com/api/share-merchant/canceSumAccredit" ## 这里填写请求的接口地址 + +header={'Content-Type': 'application/x-www-form-urlencoded'} +##业务参数 +data={ + "cmd": "balance_allot_cancel", + "merchant_id": "6763019848", + "third_id": "202207151719300aNoeMhd" +} + +body = { + "agentId":agentId, + "version": "1.0", + "reqSerialNo": reqSerialNo(), + "sign": sign_md5_base64(json.dumps(data), key), + "data": json.dumps(data) +} + +req = requests.post(url=request_url, data=body,headers=header) + + +if req.status_code != 200: + print("Http请求失败，状态码：" + str(req.status_code) + "，错误信息：" + req.text) +else: + print(req.json()) + +``` diff --git a/docs/商家余额分账/产品介绍.md b/docs/商家余额分账/产品介绍.md new file mode 100644 index 0000000..95f3bf4 --- /dev/null +++ b/docs/商家余额分账/产品介绍.md @@ -0,0 +1,163 @@ +# 1. 阅读对象 +服务商（即SaaS 一级代理商) + +# 2. 产品简介 +商家分账产品，是乐刷面向商家提供的商家资金管理产品，用以解决实际收款商家需要将收款资金按照一定的周期、比例、金额等规则分账给收款商家合作方的场景诉求，收款商家的合作方可以是合作伙伴、供应商、服务商、平台方等角色。 + +服务商在完成业务申请后，商家可以直接使用乐刷提供的“商户聚合支付平台”PC页面发起分账，或者 + +由商家的服务商通过调用接口的方式代替商家进行分账。 + +# 3. 名词解释 +| **序号** | **名词** | **解释** | +| :---: | --- | --- | +| 1 | 分账方 | 指商品或者服务的提供方，这里指实际收款商家本身。 | +| 2 | 分账接收方 | 与实际收款商家有合作关系的第三方，比如服务商、软件供应商、供货商、平台方等角色，接收分账资金的商家。 | +| 3 | 服务商 | 为实际收款商家提供各种产品和服务的提供方，这里指乐刷的1级代理商。 | +| 4 | 分账比例 | 指分账方的分账订单交易金额中，最大可分给分账接收方的资金比例。 | +| 5 | 分账关系 | 分账方和分账接收方建立绑定关系，该分账方的分账接收方仅限于建立绑定关系的对象。 | +| 6 | 分账标记 | 分账方发起交易时给交易订单（含二维码支付订单和刷卡支付订单）打上的分账标识，仅打上分账标识的订单方可参与商家分账。 | +| 7 | 待分账账户 | 分账方的分账托管账本，分账方的交易打上分账标记后，交易订单的资金将收到分账方的分账托管账本，后续的分账将从该账本中划拨资金给商户进行出款。 | +| 8 | 订单分账 | 分账模式的一种，服务商替分账方发起分账时，基于某笔的交易订单发起分账的分账模式。 | +| 9 | 余额分账 | 分账模式的一种，服务商替分账方发起分账时，基于分账方待分账账户余额发起分账的分账模式，该分账模式无需强依赖具体的交易订单。
分账方的交易订单打上分账标记后，会实时清分入账至分账方的待分账账户中。 | +| 11 | 自动分账 | 余额分账模式的一种，服务商无需开发，通过商户乐刷后台配置好的分账规则执行分账的分账模式。
手动分账，属于不配置分账规则，商户按需求分账资金给予接受方。 | + + +# 3. 适用场景 +## （1）电商平台场景分润 +某电商平台，消费者完成支付后，订单资金收到分账方的待分账账户内，商户根据与物流服务商、流量推广方的约定，将物流服务费、流量推广费通过分账功能分给物流服务商和流量推广方。 + +## （2）服务商抽佣 +在线下交易中，商家通过扫码枪、码牌、POS机等收款产品收款，消费者完成支付支付后，订单资金收到商家的待分账账户内，在经过商家授权后，线下服务商可通过分账产品收取佣金，比如 POS 推广费、智能收银设备服务费等。 + +## （3）代运营平台抽佣场景 +代运营平台给商家提供商家销售系统、小程序引流、营销发券、会员权益等会员营销服务后，采用基于商家的收款订单抽取一定比例佣金的方式收取服务费 + +## （4）设备服务运维场景 +实际收款商家的收款设备提供方给商家提供收银机器、服务后，收款商家需要按照一定的比例或者金额将维修服务费分账给设备提供方。 + +## （5）分润给合作伙伴 +实际收款商家在与他方合作时，可以用“分账”功能，将交易资金分给合作伙伴。 + +例如： + +1. 商家的供应商给商家提供消费产品供应服务，商家可通过零售交易款将部分资金分账给供应商。 +2. 代理商根据与车场商户之间的约定，将停车费分配给智能停车系统商户等。 + +# 4. 产品流程 +## 4.1 分账业务流程图 +![画板](https://cdn.nlark.com/yuque/0/2024/jpeg/1233785/1704271232345-43016a57-0b91-491c-bfe6-b1c4085182f8.jpeg) + + + +## 4.2 商户分账资金流信息流 + + +## 4.3 商户分账业务全流程 + + +![画板](https://cdn.nlark.com/yuque/0/2022/jpeg/529841/1659337621852-30aaeb15-8973-4c79-bd17-8bb597852f5e.jpeg) + +商户分账业务全流程，具体说明如下： + +### （1）商户入网 +拟参与资金分账的各方，包括分账方（即收款商家）、分账接收方（如供应商、物流方、平台方等收款商家的合作方），均需以商户的身份入网至乐刷，获取乐刷的乐刷商户号，后续的分账业务均基于乐刷商户号进行。 + + + +分账方和分账接收方，均支持对私和对公结算。 + + + +目前乐刷提供两种方式供服务商完成商户入网： + +1） API接口：服务商通过接入乐刷提供的商户入网接口，在自有的产品和系统上增加相应的商户入网资料提交入口，完成分账方和分账接收方的入网。 + +注：分账接收方如无需走交易，则无需进行费率配置等操作。 + +2）代理商平台入网：乐刷为服务商提供服务商业务管理平台，包括服务商PC后台和服务商APP两种，服务商收集到商户的资金后，可登录该平台录入并提交资料完成商户入网 + +### （2 ）商户开通分账 +商家要进行资金分账，需要给分账方开通分账的功能，开通分账的功能需要商家签署对应的协议。目前乐刷提供了两种方式供服务商推进商家完成分账功能的开通： + +1）API接口：服务商通过接口乐刷提供的商户分账开通接口，完成商户分账功能的开通。目前乐刷支持通过接口获取电子协议和通过接口上传线下纸质协议的方式，商户完成协议签署后，乐刷进行审核，审核通过即完成分账功能的开通。 + +详细的开通流程见操作指引。 + +2）商户PC开通：服务商不想进行开发的情况下，可以让商家登录乐刷提供的商户PC平台，在乐刷的商户PC平台内完成签署。 + +详细的页面操作流程见操作指引。 + +### （3）商户交易 +商户的分账资金来源于其收款产生的交易，不支持非收单资金进行分账（如外部资金充值等），目前商户可通过以下两种方式完成商户交易： + +1）API接口交易：服务商/商户通过接入乐刷提供的交易接口完成交易。 + +2）乐刷码牌、POS机交易：服务商不开发的情况下，也可以通过使用乐刷提供的码牌、码牌音箱、智能POS、传统POS等收款设备来完成收款。 + +注：目前支持按照订单维度和按照商户维度确定交易是否需要分账，如某部分订单的资金需要作为普通订单不参与分账，则需要通过接口的方式接入乐刷支付并在支付接口中标记哪笔订单是否需要分账。 + +### （4）商户分账 +乐刷的分账为异步分账，即支付成功后方可发起分账。目前乐刷提供多种方式供服务商发起分账，具体如下： + +1）商户PC分账：商户登录乐刷的商户PC平台，在商户PC页面操作和配置分账。目前商户可在商户PC平台选择配置自动分账规则和手动发起分账两种模式，商户可选任一一种发起分账。 + +自动分账：商户配置分账规则，乐刷按照商户配置的分账规则，每日将交易订单的资金分给各分账接收方 + +手动分账：商户在页面上填写分账接收方和分账金额，提交请求发起分账。 + +2）API接口分账：服务商具备自己的业务系统的情况下，可以通过调用乐刷的分账接口向乐刷发起分账请求。根据分账的模式不同，乐刷提供三种方式向乐刷发起分账请求： + ++ 订单分账：请求乐刷发起分账时，需要明确哪笔交易订单需要分账 ++ 余额分账：请求乐刷发起分账时，无需指明具体的订单，只要商户的待分账账户资金足够，并且分账给他人的资金在规定比例内，即可发起分账。 ++ 自动分账：通过接口将商户分账的规则提交给乐刷，乐刷按照提交的规则每日自动给商户发起分账。 + +### （5）资金出款 +商户发起分账请求且请求成功后，乐刷默认D1日将分账资金打款至各分账接收方的银行卡。举例：1号发起的分账，2号早上打款。 + +若商家使用乐刷的“商户聚合支付平台”发起支付，则可以选择是否分账后立即到账。注：如使用分账立即到账功能，后续会收取一定的服务费。 + +若商家使用乐刷提供的接口发起分账，暂时不支持分账后立即到账。 + + + +# 5. 产品特性 +**（1）多种落地实现方式，满足不同程度开发能力的服务商所需** + +乐刷提供分账API和商户分账后台，服务商可根据自身的开发能力，灵活选择不同的业务落地模式。 + + + +**（2）多种分账方式，满足各类业务场景的分账诉求** + +针对不同的业务分账场景，乐刷提供了多样的分账模式，可以基于交易订单发起分账，也可以基于商户余额发起分账，满足不同业务场景的复杂分账需求。 + +**** + +**（3）资金安全可控** + +基于收单资金分账，真实资金留存在乐刷备付金账户，商户的分账资金记名在乐刷的托管账本，分账后方可出金，资金安全得到保证，避免资金混用和乱用。 + + + +**（4）支持多种类型的客户参与分账** + +乐刷的分账产品，支持向个人、供应商、平台方、服务商等多方发起分账，并且可根据情况结算至对公账户和对私账户。 + + + +**（5）分账资金控制合理** + +商户进行分账，需要签署协议并约定分账比例和金额，在约定的资金范围内发起分账，避免商户的交易资金被不合理的挪用。 + + + +**（6）****可基于余额或每笔订单进行分账，可单次或多次分账，每次分给多方** + +支持按余额传入具体的分账接收方和分账金额进行分账，每日无次数限制**，**每次分账最多可以分给**50个接收方**。 + +也支持按订单传入具体的分账接收方和分账金额进行分账，一笔订单最多可以分**20次，**每次分账最多可以分给**50个接收方**。 + +# +# + diff --git a/frontend/src/features/admin/components/PublishOptionsDialog.vue b/frontend/src/features/admin/components/PublishOptionsDialog.vue index 87c1a03..ae08aca 100644 --- a/frontend/src/features/admin/components/PublishOptionsDialog.vue +++ b/frontend/src/features/admin/components/PublishOptionsDialog.vue @@ -294,6 +294,13 @@ async function handleSave() {
发布规则
+ + + ): ListingPublishOptions { return { + next_season_pass_enabled: options?.next_season_pass_enabled === true, server_options: normalizeStringList(options?.server_options), face_options: normalizeStringList(options?.face_options), rank_options: normalizeStringList(options?.rank_options), diff --git a/frontend/src/features/seller/composables/usePublishForm.ts b/frontend/src/features/seller/composables/usePublishForm.ts index 788319a..6393d1f 100644 --- a/frontend/src/features/seller/composables/usePublishForm.ts +++ b/frontend/src/features/seller/composables/usePublishForm.ts @@ -79,6 +79,7 @@ export function usePublishForm(options: UsePublishFormOptions) { const submitButtonText = computed(() => (isEditMode.value ? '提交修改' : '立即发布')) const submitLoadingText = computed(() => (isEditMode.value ? '提交中...' : '发布中...')) const showBanRecordRiskHint = false + const nextSeasonPassEnabled = computed(() => publishOptions.value.next_season_pass_enabled) const pricing = usePricingCalculator({ form, @@ -724,7 +725,9 @@ export function usePublishForm(options: UsePublishFormOptions) { if (pricing.banRecordOptions.value.length && !form.ban_record) return '请选择封禁记录' if (!form.can_change_game_name) return '请选择是否可以修改游戏名' if (!form.all_hero) return '请选择是否有全英雄' - if (!form.next_season_pass) return '请选择下赛季是否购买通行证' + if (nextSeasonPassEnabled.value && !form.next_season_pass) { + return '请选择下赛季是否购买通行证' + } if (form.depositAmountYuan === '' || Number(form.depositAmountYuan) < 0) return '请填写押金' if (!Number.isFinite(Number(form.depositAmountYuan))) return '押金格式不正确' if ( @@ -919,6 +922,7 @@ export function usePublishForm(options: UsePublishFormOptions) { passwordAndDeviceConfirmed, canPublishAfterAgreements, showBanRecordRiskHint, + nextSeasonPassEnabled, isScanOnlyServer, effectiveLoginMethodOptions, fileInput, diff --git a/frontend/src/features/seller/views/MobileSellerListingCreateView.vue b/frontend/src/features/seller/views/MobileSellerListingCreateView.vue index 4af2a98..63aac55 100644 --- a/frontend/src/features/seller/views/MobileSellerListingCreateView.vue +++ b/frontend/src/features/seller/views/MobileSellerListingCreateView.vue @@ -27,6 +27,7 @@ const { passwordAndDeviceConfirmed, canPublishAfterAgreements, showBanRecordRiskHint, + nextSeasonPassEnabled, fileInput, activeUploadKey, form, @@ -441,7 +442,12 @@ const screenshotGuides: Record = { - +