开发
API

发起退款

接口功能描述:可通过此接口将支付款退还给用户。

注意事项

  1. 交易时间超过 1 年的订单无法提交退款。
  2. 支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。
  3. 申请退款总金额不能超过订单金额。
  4. 微信渠道每个支付订单的部分退款次数不能超过 50 次,支付宝渠道不能超过 300 次。
  5. 申请退款接口的返回仅代表业务的受理情况,具体退款是否成功,需要通过退款查询接口或者退款回调接口获取结果。
  6. 银行卡支付的退款 7 天内到账,支付宝支付(余额、银行卡快捷支付等)的退款 3 个工作日内到账,微信支付(余额、银行卡快捷支付等)的退款 7 天内到账。(退款优先原路退,如用户使用尾号为 1234 的招行借记卡付款,则退款至用户尾号为 1234 的招行借记卡)。

接口说明

请求URL

https://developer.toutiao.com/api/apps/ecpay/v1/create_refund

请求方式

POST

接口频次

50QPS(小程序app_id维度)

请求头

名称

类型

必填

描述

Content-Type

string

固定值 "application/json"

请求参数

参数

类型

是否必填

最大长度

描述

示例值

app_id

string

64

小程序APPID

tt07e3715e98c9aac0

out_order_no

string

64

商户分配支付单号,标识进行退款的订单

7056505317450041644

out_refund_no

string

64

商户分配退款号,保证在商户中唯一

401020220222383672284706009088

reason

string

100

退款原因

发错地址

refund_amount

number

11

退款金额,单位分

100,即1元

sign

string

344

签名,详见地址

d716027b7b5a91a3319a061d818cc9cc

cp_extra

string

2048

开发者自定义字段,回调原样回传

一些附加信息

notify_url

string

256

商户自定义回调地址,必须以 https 开头,支持 443 端口

https://douyin.com/callback

thirdparty_id

string

条件选填

64

第三方平台服务商id,服务商模式接入必传,非服务商模式留空

tta4bad2073b900000

disable_msg

number

-

是否屏蔽担保支付的推送消息枚举值:

1:屏蔽

0:非屏蔽, 若接入POI,POI订单体系会发相关消息,所以不用再接收一次担保支付相关的消息,请传1

1

msg_page

string

1024

担保支付消息跳转页

pages/user/orderDetail/orderDetail?id=10000

请求示例

{
  "app_id": "tt07e3715e98c9aac0",
  "out_order_no": "7056505317450041644",
  "out_refund_no": "401020220222383672284706009088",
  "reason": "发错地址退款重新下单",
  "refund_amount": 12800,
  "sign": "d716027b7b5a91a3319a061d818cc9cc",
  "cp_extra": "一些附加信息",
  "notify_url": "https://douyin.com/callback"
}

响应参数

公共响应参数

参数

类型

是否必填

最大长度

描述

示例值

err_no

number

-

详见错误码

4004

err_tips

string

-

详见错误描述

退款金额超限

业务响应参数

参数

类型

是否必填

最大长度

描述

示例值

refund_no

string

-

担保交易服务端退款单号

7067465601190709538

响应示例

正常响应示例

{
  "err_no": 0,
  "err_tips": "受理成功",
  "refund_no": "7067465601190709538"
}

异常响应示例

{
  "err_no": 5004,
  "err_tips": "小程序违规,相关接口已被封禁,请咨询相关同学后进行整改",
  "refund_no": ""
}

错误码

错误码

错误描述

解决方案

0

受理成功

注:受理成功只代表退款业务受理成功,最终退款结果以异步回调或查询接口为准。

1000

内部异常

当前请求的退款可能成功也可能失败。 1、请使用相同的参数再次重试调用,需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经处理成功,接口会幂等返回成功;如果前一次退款请求没有成功,接口会重试执行退款操作; 2、或者通过退款查询接口查询退款执行结果

1001

业务繁忙,请稍后重试

该笔退款未受理,请降低频率后重试

1090

风控拦截

联系小程序平台处理

1093

系统异常,请稍微再试

请稍后原单号重试,同一笔交易的退款至少间隔3s后发起

2000

支付记录不存在

检查请求中的支付单号或商户支付单号是否正确,确认后重新发起

2004

系统异常,请联系官方运营

联系小程序平台处理

2008

签名校验异常,请使用正确的签名

请使用正确的签名重新请求

2010

参数错误

请检查参数后重试

2012

旧平台账户订单不支持分账后退款

建议联系买家进行线下退款处理

2013

服务商无对应小程序分账授权

联系小程序平台处理

2042

小程序appid无效,请检查app_id字段

检查app_id字段信息是否有误

2045

请求来源不合法

联系小程序平台处理

2047

服务商id无效,请检查thirdparty_id字段

检查thirdparty_id字段信息是否有误

2048

未查询到服务商与小程序的授权关系

检查服务商与小程序的授权关系

3000

业务异常

可通过查单接口确定退款状态和退款原因, 不能解决的联系小程序平台处理

3101

退款记录不存在

检查请求中的退款单号正确,确认后重新发起

3118

原支付单状态非法,不允许退款

查询支付是否为付成功状态

3141

分账后退款,请等待分账全部完成后再试

请等待分账全部完成后重试

4001

退款已失败

此笔退款已失败,请换单号重试

4003

退款金额无效

请检查退款金额是否正确,请求的退款金额不能大于支付总金额

4004

退款金额超限

请确认退款金额后原单重试

4010

请求信息不一致

幂等校验失败,同一个退款多次请求必须为同一个支付单并且金额相等,请检查参数后重试

4011

已超过退款期限

退款时间超过一年,无法退款,建议联系买家进行线下退款处理

4039

退款次数超过限制

建议联系买家进行线下退款处理

4100

风控分账失败导致退款失败

联系小程序平台处理

4101

服务商与特约子商户关系上,该产品授权已被解除

联系小程序平台处理

4102

商户没有退款权限

联系小程序平台处理

4103

原支付交易被冻结

联系小程序平台处理

4104

商户担保产品权限已被冻结

联系小程序平台处理

4105

退款商家账户余额不足

现无充值入口,可等待商家现金户入账,换单号重试

4200

用户账户有异常行为,已被限制收款,本次交易无法完成

建议联系买家进行线下退款处理 也可联系用户在微信解除限制,换单号重试

4201

用户账户状态异常或注销,无法原路退款

建议联系买家进行线下退款处理

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