发起退分账
接口功能描述:支付订单已经分账的情况下发生退款,可以调用此接口将已分账的资金从分账接收方的账户回退给分账方,再发起退款。
注意事项
- 分账回退以原分账单为依据,支持多次回退,申请回退总金额不能超过原分账单分给该接收方的金额。
- 对同一个分账接收方最多能发起次数有如下限制:微信对同一个分账接收方最多能发起 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 | 回退出资方商户号不能为空 | 请检查参数,原单号重试 |
2039 | 订单分账被拦截 | 当前订单分账拦截,咨询小程序平台处理 |
2042 | 小程序appid无效,请检查app_id字段 | 检查app_id字段信息是否有误 |
2047 | 服务商id无效,请检查thirdparty_id字段 | 检查thirdparty_id字段信息是否有误 |
3000 | 系统内部错误 | 可通过查单接口确定回退状态和失败原因,不能解决的联系小程序平台处理 |
4010 | 请求信息不一致,相同ma_app_id和out_return_no的多次请求为幂等请求,幂等请求需要保证多次参数的一致性 | 请检查参数后重试 |
4401 | 回退次数超过限制微信对同一个分账接收方最多能发起20次分账回退请求 | 建议进行线下处理 |
4402 | 未找到相应分账单 | 检查请求中的分账单号或商户分账单号是否正确,确认后重新发起 |
4403 | 分账状态非法,原分账单未到终态,不允许回退 | 查询分账是否为成功状态 |
4404 | 回退金额大于分账金额 | 请检查回退金额是否正确,请求的回退金额不能大于分账总金额 |
4405 | 退分账出资方不正确,为无效商户号 | 请检查参数后重试 |
4406 | 请求回退金额超出可回退金额 | 请确认回退金额后原单重试 |
4407 | 退分账接收方账户状态异常 | 联系小程序平台处理 |
4408 | 未找到相应回退单 | 检查请求中的回退单号正确,确认后重新发起 |
4409 | 订单已超过回退期限,微信180天支付宝12个月 | 建议进行线下处理 |
4410 | 退分账接收方账户不存在 | 联系小程序平台处理 |