开发
API

发起结算及分账

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

注意事项

  1. 无论是否有分账方都需要主动的调用该接口才能进行在途资金的结算。

接口说明

请求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

分账超过授权比例

检查当前除卖家商户外的其他分账方金额比例是否超限,并联系小程序平台处理

点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助