发起退分账

接口功能描述：支付订单已经分账的情况下发生退款，可以调用此接口将已分账的资金从分账接收方的账户回退给分账方，再发起退款。

注意事项

分账回退以原分账单为依据，支持多次回退，申请回退总金额不能超过原分账单分给该接收方的金额。
对同一个分账接收方最多能发起次数有如下限制：微信对同一个分账接收方最多能发起 20 次分账回退请求，其他渠道无限制。
分账回退的时限：微信分账回退的时限是 180 天，支付宝退分账有效期最长为 12 个月，其他渠道无限制。

接口说明

请求URL	https://developer.toutiao.com/api/apps/ecpay/v1/create_return
请求方式	POST
接口频次	50QPS(小程序 app_id 维度)

请求头

名称	类型	必填	描述
Content-Type	string	是	固定值 "application/json"

请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	string	是	64	小程序APPID	tt07e3715e98c9aac1
thirdparty_id	string	条件选填，服务商模式接入必传	64	第三方平台服务商 id，非服务商模式留空	tt07e3715e98c9aac0
settle_no	string	是	64	开发者侧的结算号,与out_settle_no二选一填写	7067781639492913452
out_settle_no	string	是	64	商户侧的结算号，与settle_no二选一填写	sd_T220416122114165008287419707173
out_return_no	string	是	64	开发者回退单号，相同回退单号小程序平台会进行幂等处理。只能使用数字、大小写字母_-*。	out_return_7067781639492913452
return_desc	string	是	100	回退描述，长度限制 100 个字符	分账回退demo
merchant_uid	string	是	32	回退商户号，即原分账方商户号	XCXP_000003089
return_amount	number	是	11	回退金额，单位分，取值范围：[1,10000000000]	30
sign	string	是	344	开发者对核心字段签名, 签名方式见，防止传输过程中出现意外	d98e6af1c490b36f7b72e2037f81a511
cp_extra	string	否	2048	开发者自定义字段，回调原样回传	2856

请求示例

{
  "app_id": "tt07e3715e98c9aac0",
  "out_settle_no": "sd_T220416122114165008287419707173",
  "settle_no": "7067781639492913452",
  "out_return_no": "out_return_7067781639492913452",
  "merchant_uid": "XCXP_000003089",
  "return_amount": 30,
  "return_desc": "分账回退demo",
  "notify_url": "",
  "cp_extra": "2856",
  "sign": "d98e6af1c490b36f7b72e2037f81a511"
}

响应参数

公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
err_no	number	是	-	状态码 0-业务处理成功	0
err_tips	string	是	-	错误提示信息	成功
return_info	returnInfo	条件选填，err_no=0时必填	-	分账回退基本信息	详见响应示例

业务响应参数

return_info 包含如下的字段：

参数	类型	是否必填	最大长度	描述	示例值
app_id	string	是	64	小程序APPID	tt07e3715e98c9aac1
thirdparty_id	string	条件选填，服务商模式接入必传	64	第三方平台服务商id	tt07e3715e98c9aac0
settle_no	string	是	64	平台分账单号	7067781639492913452
out_settle_no	string	是	64	商户分账单号	sd_T220416122114165008287419707173
out_return_no	string	是	64	商户回退单号	out_return_7067781639492913452
merchant_uid	string	是	32	回退商户号	XCXP_000003089
return_amount	number	是	11	回退金额，单位分，取值范围：[1,10000000000]	30
return_no	string	是	64	平台回退单号	7090899309964642562
return_status	string	是	10	回退状态成功-SUCCESS失败-FAIL处理中-PROCESSING	注意：如果返回为处理中，请勿变更商户回退单号，使用相同的参数再次发起分账回退，否则会出现资金风险在处理中状态的回退单如果5天没有成功，会因为超时被设置为已失败
fail_reason	string	否	100	回退失败的原因，此字段仅回退结果为FAIL时存在	退分账接收方账户不存在
finish_time	number	必选	10	回退完成时间，Unix 时间戳，单位秒，10 位，整型数	1644399124
cp_extra	string	否	2048	用户附加信息	2856

响应示例

正常响应示例

{
  "err_no": 0,
  "err_tips": "success",
  "return_info": {
    "CpExtra": "",
    "FailReason": "SUCCESS",
    "FinishTime": 1647332403,
    "MaAppID": "ttcfdbb96650e33350",
    "MerchantUID": "XCXP_000003087",
    "OutReturnNo": "ttcfdbb96650e33350",
    "OutSettleNo": "ot_settle_7067682742942583084_2",
    "ReturnAmount": 1,
    "ReturnNo": "7075228873218099500",
    "ReturnStatus": "SUCCESS",
    "SettleNo": "7075237473193855276",
    "ThirdpartyID": "tta4bad2073b9009c7"
  }
}

异常响应示例

{
  "err_no": 2020,
  "err_tips": "非法app_id",
  "return_info": {}
}

错误码

err_no	描述	解决方案
0	success
1000	系统错误	当前请求的退款可能成功也可能失败。1、请使用相同的参数再次重试调用，需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经处理成功，接口会幂等返回成功；如果前一次退款请求没有成功，接口会重试执行退款操作；2、或者通过退款查询接口查询退款执行结果
2020	非法app_id	请检查参数后再发起重试
2101	平台分账单号与商户原分账单号不能同时为空	请检查参数后，原单号重试
2102	退分账单号位数必须在0到64之间	请检查参数，原单号重试
2103	回退金额必须大于0	请检查参数，原单号重试
2104	回退描述长度必须在0到100之间	请检查参数，原单号重试
2105	回退出资方商户号不能为空	请检查参数，原单号重试
3000	系统内部错误	可通过查单接口确定回退状态和失败原因，不能解决的联系小程序平台处理
4010	请求信息不一致，相同ma_app_id和out_return_no的多次请求为幂等请求，幂等请求需要保证多次参数的一致性	请检查参数后重试
4401	回退次数超过限制微信对同一个分账接收方最多能发起20次分账回退请求	建议进行线下处理
4402	未找到相应分账单	检查请求中的分账单号或商户分账单号是否正确，确认后重新发起
4403	分账状态非法，原分账单未到终态，不允许回退	查询分账是否为成功状态
4404	回退金额大于分账金额	请检查回退金额是否正确，请求的回退金额不能大于分账总金额
4405	退分账出资方不正确，为无效商户号	请检查参数后重试
4406	请求回退金额超出可回退金额	请确认回退金额后原单重试
4407	退分账接收方账户状态异常	联系小程序平台处理
4408	未找到相应回退单	检查请求中的回退单号正确，确认后重新发起
4409	订单已超过回退期限，微信180天支付宝12个月	建议进行线下处理
4410	退分账接收方账户不存在	联系小程序平台处理

点击纠错

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

有帮助

没帮助

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

有帮助

没帮助

发起退分账
注意事项
接口说明
请求头
请求参数
响应参数
错误码