发起结算及分账
收藏
我的收藏

到达分账周期后，商户将交易成功的资金，结算给自己或分账给其他分账方。

使用限制

名词解释

名字	解释
在途账户	用户支付完成后，资金进入商户「在途账户」
可提现账户	商户发起结算分账/指令后，资金由「在途账户」结算或分账至商户「可提现账户」及指定的第三方分账方「可提现账户」。具体资金流担保支付企业版详见分账资金流说明，担保支付普通版详见分账资金流说明。
结算/分账	商户通过发起结算/分账指令，将资金从商户「在途账户」结算至商户「可提现账户」；若指令中指定了其它第三方分账方，则资金也会从商户「在途账户」分账至分账方「可提现账户」。
核销	在用户支付完成后，商户进行履约，对于到店类订单，商户需要将订单信息通过订单信息同步接口同步给抖音开放平台。商户完成同步后，订单达到可结算的“核销状态”，才可以结算与分账。
分账周期	指一笔订单在达到对应节点(支付/核销)后D+N天才可以发起分账。到店类订单默认核销后3天才可发起分账，其他行业默认支付后7天才可发起分账。示例： 1.支付后7天：1月1日09:00完成支付，1月8日00:00后可发起分账。 2.核销后3天：1月1日09:00完成核销，1月4日00:00后可发起分账。
部分分账	每一笔支付单可支持多次发起分账，当分账请求的finish字段传"false"时可实现多次分账请求。应用场景：支付宝渠道限制一笔订单每次分账请求只能有 2 个分账方，微信、抖音支付渠道限制一笔订单每次分账请求只能有 4 个分账方，如有多个分账方请拆分分账方并发起部分分账。

调用节点

订单类型	调用节点	示例
到店服务类订单（用户需要到店履约或到店核销）	履约或核销后 3 天才可调用该接口发起结算及分账（核销状态需要通过订单信息同步接口传入）	如果在 12.1 日上送的核销状态，那么 12.4 日零点后可随时发起结算及分账
其他订单	支付成功 7 天后才可调用该接口发起结算及分账	如果在 12.1 日支付成功，那么 12.8 日零点后可随时发起结算及分账

接口说明

如果没有开通自动结算需要主动调用该接口才能进行在途资金的结算；

同一笔订单最多允许商户发起 50 次分账请求，第 50 次分账请求无论是否指定为完结分账，都按照完结分账处理;

微信、抖音支付渠道限制一笔订单分账方为 5 个及以内的相关方（含开发者、开放平台），支付宝渠道限制一笔订单只能有 3 个及以内的相关方（含开发者、开放平台）；

2022-06-01 00:00:00 之前创建的订单不支持多次分账；

交易系统的订单目前不支持多次分账的能力；

对每一笔订单如果需要多次分账，只有在首次分账完成后才可发起后续分账（首次分账失败可更换分账单号再次发起首次分账），平台仅在首次分账时进行一次性全额计费并抽取;

沙盒环境使用说明详见担保支付-沙盒环境。

微信渠道对外分账比例（包括支付手续费，达人佣金，平台佣金，外部分账方等）不允许超过30%。

基本信息

基本信息
HTTP URL	正式环境： https://developer.toutiao.com/api/apps/ecpay/v1/settle 沙盒环境： https://open-sandbox.douyin.com/api/apps/ecpay/v1/settle
HTTP Method	POST
接口频次	30QPS(小程序 app_id 维度)

请求头

名称	类型	必填	描述
Content-Type	string	是	固定值 "application/json"

请求参数

名称	类型	是否必填	最大长度	描述	示例值
app_id	string	是	64	小程序APPID	tt07e3715e982xaac0
out_settle_no	string	是	64	开发者侧的结算单号，相同结算单号小程序平台会进行幂等处理。只能使用数字、大小写字母_-*。	ad_T220416122114165008287419707173
out_order_no	string	是	64	该笔分账单关联的商户订单单号，标识进行结算的订单（即对应支付预下单接口的"开发者侧的订单号out_order_no"参数）	out7101994117563058470
settle_desc	string	是	80	结算描述，长度限制 80 个字符	主动结算
settle_params	string	否	2048	其他分账方信息，分账分配参数 SettleParameter 数组序列化后生成的 json 格式字符串	[{\"merchant_uid\":\"M696458350318359362\",\"amount\":60}]，详见settle_params字段说明
sign	string	是	344	签名，详见签名DEMO	d98e6af1c490b36f7b72e2037f81a511
cp_extra	string	否	1000	开发者自定义字段，回调原样回传	123
notify_url	string	否	256	商户自定义分账回调地址（要求https）	https://hello.cn/callback/pay/entrance/request
thirdparty_id	string	条件选填，服务商模式接入必传	64	第三方平台服务商 id，非服务商模式留空	tte76091dd784a4a33
finish	string	条件选填	8	特别注意：该参数类型为string而非bool。 1.如果为'true'（默认值为'true'，即不传该字段等价于'true'），则该笔订单剩余未分账金额会一并结算给商户；因为每笔订单默认包含商户和开放平台两个分账方，故此时微信、抖音支付渠道settle_params最多可传3个分账方；支付宝渠道settle_params最多可传1个分账方。 2.如果为'false'，该笔订单剩余未分账的金额不会一并结算给商户，可以对该笔订单再次进行分账；因为每笔订单默认包含开放平台这一个分账方，故此时微信、抖音支付渠道settle_params最多可传4个分账方；支付宝渠道settle_params最多可传2个分账方。	'true'

settle_params参数说明

settle_params 仅支持传入第三方分账方(非商户和平台)。

参数	类型	是否必填	最大长度	描述	示例值
merchant_uid	string	是	32	外部分帐方商户号	XCXP_000003089
amount	number	是	11	分账金额，单位分，取值范围：[1,10000000000]	10

settle_params 示例：

js复制
// 需要将该json结构序列化后作为settle_params参数
[
  {
    merchant_uid: "分账方商户号",
    amount: 10, // 分账金额
  },
  {
    merchant_uid: "分账方商户号",
    amount: 8, // 分账金额
  },
];

请求示例

json复制
{
  "out_settle_no": "out_settle_no_1",
  "out_order_no": "out_order_no_1",
  "settle_desc": "分账",
  "notify_url": "https://your.callback.url",
  "cp_extra": "2856",
  "app_id": "tt07e3715e98c9aac0",
  "sign": "d98e6af1c490b36f7b72e2037f81a511",
  "settle_params": "[{\"merchant_uid\":\"M696458350318359362\",\"amount\":60}]"
}

响应参数

名称	类型	是否必填	最大长度	描述	示例值
err_no	number	是	-	详见错误码	0
err_tips	string	是	-	详见错误描述	""
settle_no	string	条件选填，err_no=0时必填	128	平台生成分账单号	N7090899309964642560

响应示例

正常示例

json复制
{
  "err_no": 0,
  "err_tips": "success",
  "settle_no": "N7090899309964642560"
}

异常示例

json复制
{
  "err_no": 2000,
  "err_tips": "单号记录不存在",
  "settle_no": ""
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	0	success	受理成功
200	1000	内部异常	当前请求可能成功也可能失败。 1.使用相同参数重试调用，需保证全部参数完全一致； 2.或者通过分账查询接口查询分账结果。
200	1002	数据异常，请检查必传参数与单号是否正确
200	1003	参数异常，与原请求数据不一致	对同一个分账单号多次请求的入参不一致，检查请求入参后重试
200	1090	风控拦截	请先按照返回的具体风控拦截原因进行处理，或咨询小程序平台处理
200	1093	系统异常，请原单号重试	当前请求可能成功也可能失败。 1.使用相同参数重试调用，需保证全部参数完全一致； 2.或者通过分账查询接口查询分账结果。
200	2000	支付记录不存在	传入的外部支付单号out_order_no查无对应支付单，检查并调整参数后重试
200	2003	无有效回调配置	请检查参数，调整回调相关参数后，原单号重试
200	2008	验签异常	请检查参数，详见签名DEMO
200	2010	业务参数处理异常	检查请求入参，修改后重试，具体原因可能为： •appID为空 •结算单号为空 •结算单号长度超限 •订单号为空 •结算描述无效，请修改后重试 •结算描述不允许超过80字符，请修改后重试 •非法自定义回调地址 •其它分账方不能传null值 •其它分账方金额必须 > 0 •其它分账方商户号不能为空 •单次分账请求的分账方仅限4个，如有多个分账方请拆分分账方并发起部分分账 •部分分账必须包含其它分账方
200	2013	服务商无对应小程序分账授权或其他	检查服务上是否有小程序的对应授权，没有授权可以通过获取预授权码进行授权
200	2014	已无可分账金额	订单已无可分账金额，具体原因可参考接口返回的err_tips信息，解决方案详见结算及分账常见问题
200	2015	分账方商户号请勿与卖家商户号相同	检查分账公式，将卖家从分账公式中删除后原单号重试
200	2016	未到结算周期无法分账	订单未到结算周期无法分账，具体原因可参考接口返回的err_tips信息，解决方案详见结算及分账常见问题
200	2020	非法app_id	请检查参数中的app_id是否有效
200	2038	小程序违规，相关接口已被封禁，请咨询相关同学后进行整改	小程序已封禁分账，请咨询小程序平台处理
200	2045	请求来源不合法	一般为开发者通过担保支付API对交易模板订单进行分账，需接入交易模板相关分账接口
200	2046	单次分账请求的分账方仅限4个，如有多个分账方请拆分分账方并发起部分分账	请检查分账方参数
200	2047	服务商id无效，请检查thirdparty_id字段	检查thirdparty_id字段信息是否有误
200	2048	未查询到服务商与小程序的授权关系	检查服务商与小程序的授权关系
200	3000	业务异常，请检查订单状态	单笔订单分账次数超限，请咨询小程序平台处理
200	3004	业务繁忙，请稍后使用原单号重试	限流（单app_id维度限流30qps），请在业务低峰期后原参数重试
200	3110	未找到相应支付单	检查原支付单是否存在
200	3111	订单状态已经成功	分账处理已成功，可使用分账结果查询接口查看具体详情
200	3113	订单状态已经终态（可能成功也可能失败）	分账处理已终态（可能成功也可能失败），可使用分账结果查询接口查看具体详情
200	3114	新/老主体xx渠道分账方未完成进件	请根据错误信息提示检查分账方商户号是否完成新/老主体下的对应渠道进件，详见【发起结算及分账接口】常见问题
200	6002	原支付单未支付成功，禁止分账	检查原支付单是否支付成功，如果是需要核销或者履约类订单，请将履约状态通过订单推送接口推送
200	6003	微信渠道对外分账比例不允许超过30%，请换金额重试	检查当前除卖家商户外的其他分账方金额比例是否超限，可以调整金额后重试
200	6004	当前订单仅允许自动结算	该订单已配置自动结算，不允许调用接口进行分账，详情见自动结算接入说明
200	6006	其它分账方分账比例超限	检查当前除卖家商户外的其他分账方金额比例是否超限，可以调整金额后重试
200	6007	存在未完成的退款，禁止分账	当前订单存在受理中的退款请求，无法发起分账，请查询退款单状态，退款完成或失败后原单号重试
200	6008	存在未完成的分账，禁止发起其它分账	当前订单存在受理中的分账请求，无法发起其它分账，请查询历史分账单状态，待历史分账单完成或失败后原单号重试