发起结算及分账
接口功能描述：到达分账周期后，商户将交易成功的资金，结算给自己或分账给其他分账方。
注意事项
- 无论是否有分账方都需要主动的调用该接口才能进行在途资金的结算。
接口说明
请求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 |
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 | 订单分账被拦截 | 当前订单分账拦截，咨询小程序平台处理 |
3000 | 业务异常，请检查订单状态 单笔订单分账次数过多 | 单笔订单分账次数超限，请咨询小程序平台处理 |
3004 | 业务繁忙，请稍后使用原单号重试 | 限流（单app_id维度限流30qps），请在业务低峰期后原参数重试 |
3106 | 金额需大于0 | 分账金额需大于0 |
3110 | 未找到相应支付单 | 检查原支付单是否存在 |
3111 | 订单状态已经成功 | 分账处理已成功，可使用分账结果查询接口查看具体详情 |
3113 | 订单状态已经终态（可能成功也可能失败） | 分账处理已终态（可能成功也可能失败），可使用分账结果查询接口查看具体详情 |
3114 | Uid[%s]会员未开户 | 检查下游各渠道（wx/ali）的分账绑定关系，并联系小程序平台处理 |
3119 | 原支付单未支付，不允许结算 | 如说明，未支付成功的支付单无法分账 |
3141 | 请求可操作金额失败，原单总金额：%d，已操作金额：%d，剩余可操作金额：%d | 当前已分账金额或分账前已退款金额已超限，无法再次发起全新的分账请求 |
6003 | 分账超过授权比例 | 检查当前除卖家商户外的其他分账方金额比例是否超限，并联系小程序平台处理 |
