发起结算及分账
开发环境
http://dev-cn.your-api-server.com
开发环境
http://dev-cn.your-api-server.com
POST
https://developer.toutiao.com/api/apps/ecpay/v1/settle
名词解释
| 名字 | 解释 |
|---|---|
| 在途账户 | 用户支付完成后，资金进入商户「在途账户」 |
| 可提现账户 | 商户发起结算分账/指令后，资金由「在途账户」结算或分账至商户「可提现账户」及指定的第三方分账方「可提现账户」，具体资金流详见分账资金流说明。 |
| 结算/分账 | 商户通过发起结算/分账指令，将资金从商户「在途账户」结算至商户「可提现账户」；若指令中指定了其它第三方分账方，则资金也会从商户「在途账户」分账至分账方「可提现账户」。 |
| 核销 | 在用户支付完成后，商户进行履约，对于到店类订单，商户需要将订单信息通过订单信息同步接口同步给抖音开放平台。 商户完成同步后，订单达到可结 算的“核销状态”，才可以结算与分账。 |
| 分账周期 | 指一笔订单在达到对应节点(支付/核销)后D+N天才可以发起分账。到店类订单默认核销后3天才可发起分账，其他行业默认支付后7天才可发起分账。 示例： 支付后7天：1月1日09:00完成支付，1月8日00:00后可发起分账。 核销后3天：1月1日09:00完成核销，1月4日00:00后可发起分账。 |
| 部分分账 | 每一笔支付单可支持多次发起分账，当分账请求的finish字段传"false"时可实现多次分账请求。 应用场景：每次分账请求最多允许4个分账方，当分账方过多时，可使用部分分账多次请求同一笔支付单。 |
接口说明
1.
2.
3.
4.
5.
6.
7.
8.
调用节点
核销后 3 天的计算逻辑：如果在 12.1 日上送的核销状态，那么 12.4 日零点后可随时发起结算及分账。
支付 7 天后的计算逻辑：如果在 12.1 日支付成功，那么 12.8 日零点后可随时发起结算及分账。
基本信息
| 基本信息 | |
|---|---|
| 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 维度) |
| 参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
| merchant_uid | string | 是 | 32 | 外部分帐方商户号 | XCXP_000003089 |
| amount | number | 是 | 11 | 分账金额，单位分，取值范围：[1,10000000000] | 10 |
错误码
| 错误码err_no | 描述err_tips | 排查建议 |
|---|---|---|
| 0 | success | 受理成功 |
| 1000 | 内部异常 | 当前请求可能成功也可能失败。 1.使用相同参数重试调用，需保证全部参数完全一致； 2.或者通过分账查询接口查询分账结果。 |
| 1002 | 数据异常，请检查必传参数与单号是否正确 | |
| 1003 | 参数异常，与原请求数据不一致 | 对同一个分账单号多次请求的入参不一致，检查请求入参后重试 |
| 1090 | 风控拦截 | 请先按照返回的具体风控拦截原因进行处理，或咨询小程序平台处理 |
| 1093 | 系统异常，请原单号重试 | 当前请求可能成功也可能失败。 1.使用相同参数重试调用，需保证全部参数完全一致； 2.或者通过分账查询接口查询分账结果。 |
| 2000 | 支付记录不存在 | 传入的外部支付单号out_order_no查无对应支付单，检查并调整参数后重试 |
| 2003 | 无有效回调配置 | 请检查参数，调整回调相关参数后，原单号重试 |
| 2008 | 验签异常 | 请检查参数，详见签名DEMO |
| 2010 | 业务参数处理异常 | 检查请求入参，修改后重试，具体原因可能为： appID为空 结算单号为空 结算单号长度超限 订单号为空 结算描述无效，请修改后重试 结算描述不允许超过80字符，请修改后重试 非法自定义回调地址 其它分账方不能传null值 其它分账方金额必须 > 0 其它分账方商户号不能为空 单次分账请求的分账方仅限4个，如有多个分账方请拆分分账方并发起部分分账 部分分账必须包含其它分账方 |
| 2013 | 服务商无对应小程序分账授权 或 其他 | 检查服务上是否有小程序的对应授权，没有授权可以通过获取预授权码进行授权 |
| 2014 | 已无可分账金额 | 订单已无可分账金额，具体原因可参考接口返回的err_tips信息， 解决方案详见结算及分账常见问题 |
| 2015 | 分账方商户号请勿与卖家商户号相同 | 检查分账公式，将卖家从分账公式中删除后原单号重试 |
| 2016 | 未到结算周期无法分账 | 订单未到结算周期无法分账，具体原因可参考接口返回的err_tips信息， 解决方案详见结算及分账常见问题 |
| 2020 | 非法app_id | 请检查参数中的app_id是否有效 |
| 2038 | 小程序违规，相关接口已被封禁，请咨询相关同学后进行整改 | 小程序已封禁分账，请咨询小程序平台处理 |
| 2045 | 请求来源不合法 | 一般为开发者通过担保支付API对交易模板订单进行分账，需接入交易模板相关分账接口 |
| 2046 | 单次分账请求的分账方仅限4个，如有多个分账方请拆分分账方并发起部分分账 | 请检查分账方参数 |
| 2047 | 服务商id无效，请检查thirdparty_id字段 | 检查thirdparty_id字段信息是否有误 |
| 2048 | 未查询到服务商与小程序的授权关系 | 检查服务商与小程序的授权关系 |
| 3000 | 业务异常，请检查订单状态 | 单笔订单分账次数超限，请咨询小程序平台处理 |
| 3004 | 业务繁忙，请稍后使用原单号重试 | 限流（单app_id维度限流30qps），请在业务低峰期后原参数重试 |
| 3110 | 未找到相应支付单 | 检查原支付单是否存在 |
| 3111 | 订单状态已经成功 | 分账处理已成功，可使用分账结果查询接口查看具体详情 |
| 3113 | 订单状态已经终态（可能成功也可能失败） | 分账处理已终态（可能成功也可能失败），可使用分账结果查询接口查看具体详情 |
| 3114 | 新/老主体xx渠道分账方未完成进件 | 请根据错误信息提示检查分账方商户号是否完成新/老主体下的对应渠道进件， 详见【发起结算及分账接口】常见问题 |
| 6002 | 原支付单未支付成功，禁止分账 | 检查原支付单是否支付成功，如果是需要核销或者履约类订单，请将履约状态通过订单推送接口推送 |
| 6003 | 微信渠道对外分账比例不允许超过30%，请换金额重试 | 检查当前除卖家商户外的其他分账方金额比例是否超限，可以调整金额后重试 |
| 6004 | 当前订单仅允许自动结算 | 该订单已配置自动结算，不允许调用接口进行分账，详情见 自动结算接入说明 |
| 6006 | 其它分账方分账比例超限 | 检查当前除卖家商户外的其他分账方金额比例是否超限，可以调整金额后重试 |
| 6007 | 存在未完成的退款，禁止分账 | 当前订单存在受理中的退款请求，无法发起分账，请查询退款单状态，退款完成或失败后原单号重试 |
| 6008 | 存在未完成的分账，禁 止发起其它分账 | 当前订单存在受理中的分账请求，无法发起其它分账，请查询历史分账单状态，待历史分账单完成或失败后原单号重试 |
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://developer.toutiao.com/api/apps/ecpay/v1/settle' \
--header 'Content-Type: application/json' \
--data-raw '{
"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}]"
}'响应示例响应示例
200 - 示例 1
{
"err_no": 0,
"err_tips": "string",
"settle_no": "string"
}请求参数
Body 参数application/json
返回响应
修改于 2023-12-04 09:11:05