发起结算及分账

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

注意事项

无论是否有分账方都需要主动的调用该接口才能进行在途资金的结算；
同一笔订单最多允许商户发起 50 次分账请求，第 50 次分账请求无论是否指定为完结分账，都按照完结分账处理；
一次分账请求中分账方数量限制 4 个以内（含 4 个）
2022-06-01 00:00:00 之前创建的订单不支持多次分账；
交易2.0的订单目前不支持多次分账的能力；
对每一笔订单如果需要多次分账，只有在首次分账完成后才可发起后续分账（首次分账失败可更换分账单号再次发起首次分账）；

接口说明

请求URL	https://developer.toutiao.com/api/apps/ecpay/v1/settle
请求方式	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\":\"696458350318359362\",\"amount\":60}]，详见settle_params字段说明
sign	string	是	344	签名，详见	d98e6af1c490b36f7b72e2037f81a511
cp_extra	string	否	2048	开发者自定义字段，回调原样回传	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'），则该笔订单剩余未分账金额会一并结算给商户； 2. 如果为'false'，该笔订单剩余未分账的金额不会一并结算给商户，可以对该笔订单再次进行分账；	'true'

settle_params：仅支持传入第三方分账方（非商户和平台）

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

settle_params 示例：

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

请求示例

{
  "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\":\"696458350318359362\",\"amount\":60}]"
}

响应参数

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

响应示例

正常响应示例

{
  "err_no": 0,
  "err_tips": "success",
  "settle_no": "7090899309964642560"
}

异常响应示例

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

错误码

err_no	描述	说明及建议解决方案
0	success	受理成功
1000	内部异常	当前请求可能成功也可能失败。 1.使用相同参数重试调用，需保证全部参数完全一致； 2.或者通过分账查询接口查询分账结果。
1002	数据异常，请检查必传参数与单号是否正确
2000	支付记录不存在	传入的外部支付单号out_order_no查无对应支付单，检查并调整参数后重试
2003	无有效回调配置	请检查参数，调整回调相关参数后，原单号重试
2013	服务商无对应小程序分账授权或其他	当前服务商无为该小程序代为发起分账权限
2014	已无可分账金额	查询是否已有成功或在途分账；或分账前已退款
2015	分账方商户号请勿与卖家商户号相同	检查分账公式，将卖家从分账公式中删除后原单号重试
2016	创建订单起N天内禁止分账	过早分账，请在支付/核销后对应账期发起分账
2020	非法app_id	请检查参数中的app_id是否有效
2021	订单号为空	请检查参数，调整外部支付单号后重试
2028	非法自定义回调地址	请检查参数，调整回调地址参数后，原单号重试
2033	结算号为空	请检查参数，调整外部分账单号后重试
2034	结算描述为空	请检查参数中的结算描述是否有效
2035	结算描述超过80个字符	请检查参数，修复结算描述过长后，原单号重试
2037	非法merchant_uid	检查分账公式merchant_uid是否合法
2038	小程序违规，相关接口已被封禁，请咨询相关同学后进行整改	小程序已封禁分账，请咨询小程序平台处理
2039	订单分账被拦截	当前订单分账拦截，咨询小程序平台处理
2042	小程序appid无效，请检查app_id字段	检查app_id字段信息是否有误
2046	单次分账请求的分账方仅限4个，如有多个分账方请拆分分账方并发起部分分账	请检查分账方参数
2047	服务商id无效，请检查thirdparty_id字段	检查thirdparty_id字段信息是否有误
2048	未查询到服务商与小程序的授权关系	检查服务商与小程序的授权关系
3000	业务异常，请检查订单状态单笔订单分账次数过多	单笔订单分账次数超限，请咨询小程序平台处理
3004	业务繁忙，请稍后使用原单号重试	限流（单app_id维度限流30qps），请在业务低峰期后原参数重试
3106	金额需大于0	分账金额需大于0
3110	未找到相应支付单	检查原支付单是否存在
3111	订单状态已经成功	分账处理已成功，可使用分账结果查询接口查看具体详情
3113	订单状态已经终态（可能成功也可能失败）	分账处理已终态（可能成功也可能失败），可使用分账结果查询接口查看具体详情
3114	Uid[%s]会员未开户	检查下游各渠道（wx/ali）的分账绑定关系，并联系小程序平台处理
3119	原支付单未支付，不允许结算	如说明，未支付成功的支付单无法分账
3141	请求可操作金额失败，原单总金额：%d，已操作金额：%d，剩余可操作金额：%d	当前已分账金额或分账前已退款金额已超限，无法再次发起全新的分账请求
6003	分账超过授权比例	检查当前除卖家商户外的其他分账方金额比例是否超限，并联系小程序平台处理
6007	存在未完成的退款，禁止分账	当前订单存在受理中的退款请求，无法发起分账，请查询退款单状态，退款完成或失败后原单号重试
6008	存在未完成的分账，禁止发起其它分账	当前订单存在受理中的分账请求，无法发起其它分账，请查询历史分账单状态，待历史分账单完成或失败后原单号重试

点击纠错

该文档是否对你的开发有所帮助？

有帮助

没帮助

该文档是否对你的开发有所帮助？

有帮助

没帮助

发起结算及分账
注意事项
接口说明
请求头
请求参数
响应参数
响应示例
错误码