发起分账
收藏
一笔订单到达结算周期后，开发者可以通过分账接口将这笔订单产生的资金结算给各个分账方。
使用限制
无
注意事项
分账规则
- 按小程序维度进行配置，一般有两类：
- 核销 D+N。例如核销 D+3，如果按整单分账，则要求整单到达“终态”3 个自然日后可以分账；如果按券分账，则要求券到达终态3个自然日后可以分账。“终态”表示所有的券/商品已核销或已退款。
- 支付D+N。例如支付D+7，表示订单支付成功7个自然日后可以分账。
- CPS 订单比较特殊，统一结算规则是核销 D+3。
- 如对上述结算规则有特殊需求，请联系对应行业技术支持人员。
- 如果是次卡订单，则每次发起请求会将已经履约的金额进行分账。
举个例子
小程序 A 是核销 D+3 分账，用户的一笔订单 X 买了 5 张团购券
按整单分账时，对于订单 X，其中 3 张先核销，剩余 2 张再退款，最终退款完成的时间就是订单到达终态的时间。订单到达终态 3 天后，则可以发起分账
按券分账时，对于订单 X，其中 1 张券先核销，核销 3 天后可以发起这张券的分账
如果是次卡订单，对于订单 X，履约了第 1、2 次发起分账，则本次分账会将第 1、2 次对应的金额进行结算
分账类型
- 整单分账
- 按券分账
- 分账规则和整单一致，如果整单是按核销D+3，按券结算也需要满足券核销D+3。
- 整单分账和券分账互斥，即一笔订单如果有1张券已经分账了，则不再允许发起整单分账，其他券都要按券发起结算。
- 支付D+N结算的小程序不允许发起券分账，只能整单分账
分账发起方
- 开发者，即主动分账
- 平台，即自动分账
- 配置了自动分账后，不允许开发者再发起主动分账
基本信息
基本信息 | |
|---|---|
HTTP URL | https://open.douyin.com/api/apps/trade/v2/settle/create_settle |
HTTP Method | POST |
Scope | industry_open.trade.settle |
权限要求 |
|
请求头
参考通用参数
请求参数
名称 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|
out_order_no | string | 是 | 开发者侧订单 id，长度 <= 64 字节，与唯一 order_id 关联 | out_order_example_1 |
out_settle_no | string | 是 | 开发者侧分账单 id，分账请求的唯一标识，长度 <= 64 字节 | out_settle_example_1 |
item_order_id | string | 否 | 开平侧item_order_id, 按券分账时必填，长度 <= 64 字节 注意：2023.03.31号后下单的订单才可以使用该字段进行按券分账 | ot78318372940872837161 |
settle_desc | string | 是 | 分账描述，长度 <= 512 字节 | 分账描述 |
settle_params | string | 否 | 其他分账方（除卖家之外的），长度 <= 512 字节 | [{\"merchant_uid\":\"分账方商户号1\",\"amount\":100}] |
cp_extra | string | 否 | 开发者自定义透传字段，长度 <= 2048 字节，不支持二进制 | test |
notify_url | string | 否 | 分账结果通知地址，若不填，默认使 用在行业模板配置-消息通知中指定的回调地址
| https://www.xxxx.com |
settle_params 字段说明示例："[{\"merchant_uid\":\"分账方商户号 1\",\"amount\":100}]"
名称 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|
merchant_uid | string | 是 | 进件商户 id（除了卖家以外的其他分账方） | 分账方商户号 1 |
amount | int64 | 是 | 分账金额，单位[分]，amount>0 | 100 |
请求示例
- 整单分账
curl -X POST ' -H 'Content-Type:application/json' --data-raw '{ "out_order_no":"out_order_example_1", "out_settle_no":"out_settle_example_1", "settle_desc":"分账描述", "settle_params":"[{\"merchant_uid\":\"分账方商户号1\",\"amount\":100}]", "cp_extra":"test", "notify_url":"https://www.xxxx.com" }'
- 按券分账
curl -X POST ' -H 'Content-Type:application/json' --data-raw '{ "out_order_no":"out_order_example_1", "out_settle_no":"out_settle_example_1", "item_order_id":"ot78318372940872837161", "settle_desc":"分账描述", "settle_params":"[{\"merchant_uid\":\"分账方商户号1\",\"amount\":100}]", "cp_extra":"test", "notify_url":"https://www.xxxx.com" }'
响应参数
名称 | 类型 | 描述 | 示例值 |
|---|---|---|---|
data | object | 分账受理相关信息 | 见下文示例 |
extra | object | 额外信息 |
data 字段
名称 | 类型 | 描述 | 示例值 |
|---|---|---|---|
settle_id | string | 抖音开平侧分账 id，长度 <= 64 个字节 | ot7053723547314981164 |
inner_settle_id | string | 用于退分账场景，对应退分账接口文档中settle_no，长度<= 64字节 | 7115250727504854611 |
extra 字段
名称 | 类型 | 描述 | 示例值 |
|---|---|---|---|
error_code | int64 | 父错误码，标识错误域 | 0 |
description | string | 父错误码描述 | |
sub_error_code | int64 | 子错误码，标识具体错误信息，详见下面错误码说明 | 0 |
sub_description | string | 子错误码描述 | success |
settle_id | string | 抖音开平侧分账 id，长度 <= 64 个字节 | ot7053723547314981164 |
inner_settle_id | string | 用于退分账场景，对应退分账接口文档中settle_no，长度<= 64字节 | 7115250727504854611 |
响应示例
正常示例
{ "data": { "settle_id": "ot7053723547314981164", // 抖音开平侧分账单id "inner_settle_id": "7115250727504854611" // 用于退分账场景 }, "extra": { "sub_error_code": 0, "sub_description": "success", "logid": "2022092115392201020812109511046", "now": 1663745962686, "error_code": 0, "description": "success" } }
异常示例
{ "extra": { "sub_error_code": 23002, "sub_description": "订单id,分账单id至少指定一个", "logid": "2022092115392201020812109511046", "now": 1663745962686, "error_code": 2190004, "description": "应用未获得该能力, 请去https://open.douyin.com/申请" } }
错误码
子错误码 | 错误提示 | 建议解决方案 |
|---|---|---|
23000 | 抱歉，出错了！请稍后重试 | 原单号发起重试 |
23001 | bad app_id | 检查请求参数 |
23002 | 订单id,分账单id至少指定一个 | |
23003 | out_order_no不能为空 | |
23004 | out_settle_no不能为空 | |
23005 | settle_desc不能为空 | |
23006 | cp_extra too long | |
23007 | settle_param too long | |
23008 | 分账方商户号不能为空 | |
23009 | 分账方金额不能小于1 | |
23010 | settle_desc too long | |
23101 | 订单不存在,无法分账 | 检查订单号是否正确，或者订单号与appid是否匹配 |
23102 | 订单未支付,无法分账 | 检查订单是否支付 |
23103 | 小程序在禁止分账名单中,无法分账 | |
23104 | 服务商在 禁止分账名单中,无法分账 | |
23105 | 支付后不满N天,无法分账 | |
23106 | 核销后不满N天,无法分账 | |
23107 | 订单未完成,无法分账 | 查询券状态，检查是否每张券都已核销/退款 |
23108 | 单笔订单分账次数过多 | |
23109 | 分账金额超过授权比例 | |
23110 | 服务商无对应小程序分账授权 | |
23111 | out_settle_no已存在,请用查询接口查询分账结果 | 建议用分账查询接口查询分账结果，有以下场景：
|
23112 | 已无可分账金额 | 检查订单是否已退款或已分账 |
23113 | 该订单不允许分账 | |
23117 | 该订单属于自动结算订单, 无需请求分账 | 属于自动分账的小程序，可以按订单维度查询分账 |
23118 | 不允许整单结算,请按券发起结算 | 一笔订单中已有券结算，其他券也只能按券结算 |
23119 | 不允许发起券结算 | 支付D+N结算的小程序不允许发起券结算 |
23120 | 券未核销,无法分账 | 查询券状态，检查券是否核销 |
23121 | 券结算功能灰度中,请联系运营开通 |
