发起退款
接口功能描述：可通过此接口将支付款退还给用户。
注意事项
- 交易时间超过 1 年的订单无法提交退款。
- 支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。
- 申请退款总金额不能超过订单金额。
- 微信渠道每个支付订单的部分退款次数不能超过 50 次，支付宝渠道不能超过 300 次。
- 申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口或者退款回调接口获取结果。
- 银行卡支付的退款 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 | 用户账户状态异常或注销，无法原路退款 | 建议联系买家进行线下退款处理 |
