发起退款
收藏
我的收藏

可通过此接口将支付款退还给用户。

使用限制

无

接口说明

交易时间超过 1 年的订单无法提交退款。

支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。

申请退款总金额不能超过订单金额。

微信渠道每个支付订单的部分退款次数不能超过 50 次，支付宝渠道不能超过 300 次。

申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口或者退款回调接口获取结果。

银行卡支付的退款 7 天内到账，支付宝支付（余额、银行卡快捷支付等）的退款 3 个工作日内到账，微信支付（余额、银行卡快捷支付等）的退款 7 天内到账。（退款优先原路退，如用户使用尾号为 1234 的招行借记卡付款，则退款至用户尾号为 1234 的招行借记卡）。

沙盒环境使用说明详见担保支付-沙盒环境。

基本信息

基本信息
请求URL	正式环境： https://developer.toutiao.com/api/apps/ecpay/v1/create_refund 沙盒环境： https://open-sandbox.douyin.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	签名，详见签名DEMO	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	退款完成后推送给用户的抖音消息跳转页面，开发者需要传入在app.json中定义的链接，如果不传则跳转首页。	pages/user/orderDetail/orderDetail?id=10000

请求示例

json复制
{
  "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	否	128	担保交易服务端退款单号	N7067465601190709538

响应示例

正常示例

json复制
{
  "err_no": 0,
  "err_tips": "success",
  "refund_no": "N7067465601190709538"
}

异常示例

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

错误码

HTTP 状态码	错误码 err_no	错误描述 err_tips	排查建议
200	0	success	注：该响应代表退款业务受理成功，系统开始处理退款。最终退款结果以异步回调或查询接口为准。
200	1000	内部异常	当前请求的退款可能受理成功也可能失败。 1、请使用相同的参数再次重试调用，需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经受理成功，接口会幂等返回受理成功；如果前一次退款请求没有成功，接口会重试执行退款操作； 2、或者通过退款查询接口查询退款执行结果
200	1001	业务繁忙，请稍后重试	该笔退款未受理，请降低频率后重试
200	1090	风控拦截	联系小程序平台处理
200	1093	系统异常，请稍后再试	请稍后原单号重试，同一笔交易的退款至少间隔3s后发起
200	2000	支付记录不存在	检查请求中的支付单号或商户支付单号是否正确，确认后重新发起
200	2004	当日金额或笔数超限，请明天再试	退款金额或笔数超限，请明天再试，详见退款常见问题
200	2008	签名校验异常，请使用正确的签名	请使用正确的签名重新请求，详见签名DEMO
200	2010	参数错误	请检查参数后重试
200	2012	旧平台账户订单不支持分账后退款	建议联系买家进行线下退款处理
200	2013	服务商无对应小程序分账授权	联系小程序平台处理
200	2042	小程序appid无效，请检查app_id字段	检查app_id字段信息是否有误
200	2045	请求来源不合法	联系小程序平台处理
200	2047	服务商id无效，请检查thirdparty_id字段	检查thirdparty_id字段信息是否有误
200	2048	未查询到服务商与小程序的授权关系	检查服务商与小程序的授权关系
200	3000	业务异常	可通过查单接口确定退款状态和退款原因，不能解决的联系小程序平台处理
200	3118	原支付单状态非法，不允许退款	查询支付是否为付成功状态
200	3141	分账后退款，请等待分账全部完成后再试	请等待分账全部完成后重试
200	4001	退款已失败	此笔退款已失败，请换单号重试
200	4003	退款金额无效	请检查退款金额是否正确，请求的退款金额不能大于支付总金额
200	4004	退款金额超限	请确认退款金额后原单重试
200	4010	请求信息不一致	幂等校验失败，同一个退款多次请求必须为同一个支付单并且金额相等，请检查参数后重试
200	4011	已超过退款期限	退款时间超过一年，无法退款，详见退款常见问题
200	4039	退款次数超过限制	建议联系买家进行线下退款处理
200	4100	风控分账失败导致退款失败	联系小程序平台处理
200	4101	服务商与特约子商户关系上，该产品授权已被解除	联系小程序平台处理
200	4102	商户没有退款权限	联系小程序平台处理
200	4103	原支付交易被冻结	联系小程序平台处理
200	4104	商户担保产品权限已被冻结	联系小程序平台处理
200	4105	退款商家账户余额不足	现无充值入口，可等待商家现金户入账，换单号重试
200	4200	用户账户有异常行为，已被限制收款，本次交易无法完成	方案一：建议联系买家进行线下退款处理；方案二：如果是微信或支付宝渠道退款，也可联系用户在微信或支付宝平台解除账号限制，解除限制后换单号重试
200	4201	用户账户状态异常或注销，无法原路退款	建议联系买家进行线下退款处理
200	4202	用户账户状态异常无法退款	商户现金户余额不足无法原路退且用户账户状态异常无法实现退款，请等待商户现金户余额充足再次发起退款或联系买家进行线下退款处理