开发
API

发起退分账

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

注意事项

  1. 分账回退以原分账单为依据,支持多次回退,申请回退总金额不能超过原分账单分给该接收方的金额。
  2. 对同一个分账接收方最多能发起次数有如下限制:微信对同一个分账接收方最多能发起 20 次分账回退请求,其他渠道无限制。
  3. 分账回退的时限:微信分账回退的时限是 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

退分账接收方账户不存在

联系小程序平台处理

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