发起退款
当开发者需要替用户发起退款时,可用该接口替用户发起退款。
使用限制
请不要滥用退款能力,如果发现滥用退款能力,平台会进行惩处。
接口说明
-
一笔订单可以多次退款。微信渠道不超过 50 次,支付宝渠道不超过 300 次。
-
交易时间超过 1 年的订单无法提交退款。
-
银行卡支付的退款 7 天内到账,支付宝支付(余额、银行卡快捷支付等)的退款 3 个工作日内到账,微信支付(余额、银行卡快捷支付等)的退款 7 天内到账。(退款优先原路退,如用户使用尾号为 1234 的招行借记卡付款,则退款至用户尾号为 1234 的招行借记卡)。
退款流程
退款流程如下:
过期自动退说明
-
过期自动退的退款被拒绝退款后,不会再次发起。
-
在交易系统产生的订单,如果用户购买的商品是过期退商品,在商品到达过期时间后,交易系统会自动发起退款,创建退款单,退款流程和用户发起退款流程相同。
-
发起过期自动退条件:
-
非 POI 商品:
-
前端传入合法的商品过期时间。
-
前端传入的 goodsLabels 中包含过期退标签。
-
POI 团购商品:
-
POI 商品设置了过期时间。
-
POI 商品的 sub_title 包含过期退标签。
-
可以通过查询券状态接口的valid_end_time字段获取商品的过期时间
-
担保支付不会自动发起过期自动退,仍需开发者处理。 过期自动退的退款单由系统创建,因此 退款申请回调和状态通知回调 cp_extra 会是空值。
外部退款单号说明:
- 外部退款单号务必确保在同一小程序内不会重复
未核销/已核销的 item 需要分开发起退款
- 开发者发起退款,一次退款不能同时包含核销前和核销后的item_order,请分别发起核销前或核销后退款。
部分金额退功能说明
在某些特殊的场景下(次卡、酒旅订单等),用户退 item_order 的退款金额不等于实付金额,开发者需要指定用户退款的 item_order 的退款金额(退款 item_order 部分金额)。交易系统也支持了该特殊场景,允许开发者在前端组件和开发者发起退款的 Open API 指定 item_order 退款金额。
开发者需要使用部分金额退功能,请联系对应的行业运营开通。
功能限制:非门票类CPS订单,不能指定 item_order 退款部分金额;门票类CPS订单支持核销前退款部分金额,不支持核销后退款部分金额。门票类CPS订单的每个item_order退款金额需 >= 实付金额*70%。
不指定 item_order 退款金额 和 普通的退款(退实付金额)相同。
如果该 item_order 已经退款成功,不能再发起退款。不支持已退款成功的 item_order,再发起退款。
次卡退款说明
次卡仅支持开发者用openAPI发起退款,开发者必须指定item_order和对应的退款金额
次卡仅支持退剩余未核销金额,已核销的金额不支持退款
次卡仅允许退款一次,即如果次卡已退款成功则无法再次发起退款
次卡不支持过期自动退
请求头
请求参数
对于历史上没有接入过“担保支付”和“交易模板 1.0”两个系统的开发者可以忽略“旧系统”这个概念
- 新系统订单退款,必传item_order_detail字段
- 旧系统订单退款,必传refund_total_amount,(旧系统是指通过担保交易和旧交易模板产生的订单)
- item_order_detail 和 refund_total_amount 不能同时传入
- 通过开发者接口发起退款,请注意 item_order 的状态(待使用和已核销可以发起退款,其他状态无法发起退款)
- 用户发起退款,只有 item_order 的状态为待使用状态才可以发起退款
- 开发者发起退款和用户发起退款、过期自动退都需要退款审核,需要调用 退款审核结果同步 接口同步同意退款还是拒绝退款。
担保交易、旧交易系统订单退款的请求示例
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/refund/create_refund' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
"out_order_no": "123123131",
"out_refund_no": "123123",
"cp_extra": "extra_info",
"order_entry_schema": {
"path": "page/xxx",
"params": "{"id":1}"
},
"notify_url": "https://xxx",
"refund_total_amount": 100
}'
错误码
错误码 | 错误提示 | 建议解决方案 |
---|---|---|
10000 | 商品单(ots721212128374372)不能指定退款金额 | cps订单不允许指定退款金额,除了以下情况,cps核销前退款: 门票类型允许部分退,部分退金额>=实付金额*70% 次卡类型允许部分退,部分退金额 <= 未核销金额 cps订单当前不允许核销后退款 |
10000 | 参数不合法:(ots72128388728472)商品单不存在 | 按以下步骤排查: 检查item_order_id是否正确,注意是item_order_id,不是商户单id 检查out_order_no与item_order_id是否匹配。用查询券状态接口查询商户单下的所有item列表,检查item_order_id是否在列表中。 |
11001 | 访问未授权 | 退款金额小于实付金额的被判断为部分退款,需要申请权限,请联系行业运营 |
20000 | 订单不存在 | 检查out_order_no是否正确,out_order_id与appid是否匹配 |
22000 | 订单状态不支持退款 | 订单未支付或已关闭则不允许再发起退款 |
22001 | (ots7218277338394847)商品单状态不支持退款 | 订单item子单的状态不允许发起退款,用查询券状态接口查询item单的状态: item处于[退款中,退款完成]状态时,不允许退款 预约类的item,处于[退款中,退款完成,预约中]状态时不允许退款。 下单即预约(门票)的item,预约中不允许退款,可以取消预约后发起退款 先买后约(预售券)的item,预约中/预约成功状态不允许退款,可以取消预约或者等预约完成时间过后,item变为已核销状态后,再发起退款 |
22002 | 无可退款的商品单 | 订单下所有的item处于不可退状态时,无法发起退款,参考22001的说明 |
22004 | 外部退款单号重复了 | 开发者生成的外部退款单号以前已经用过了,请重新生成 |
22005 | 因cps限制订单不允许退款 | cps有订单对退款有一些程序处理过程中的限制 |
22006 | 退款单状态不允许设置商家审核结果 | 退款审核状态前置步骤未完成,等几分钟后再重新发起 |
22007 | 超出单次最大可退款的商品数量 | 一般是单次退款item订单的数量超过了100 |
22008 | 退款商品数量超过可退款的商品数量 | 用户可以发起退款的item单数小于请求数 |
22009 | 不支持同时发起核销前和核销后退款 | 发起退款的item单列表中包含已核销和未核销的,需要分别发起退款 |
22010 | 只允许整单退款,请发起整单退款 | 门票、下单即预约场景,订单只允许整单退 |
22011 | 加价单不允许发起退款 | 预约失败时加价单会自动发起退款,不允许开发者发起退款。 |
22012 | 退款来源不支持退款 | 退款来源有: 用户,开发者 |
22013 | 退款金额不符合条件,提交退款失败 | 几种可能的场景: CPS订单发起核销前部分退款,退款比例有限制,门票类CPS订单的每个item_order退款金额需 >= 实付金额*70% 次卡类型,发起退款金额 > 剩余未核销金额;需要修改退款金额重新发起 外卖类型,发起退款金额 > 剩余可退金额;需要修改退款金额重新发起 小程序开通了item多次退白名单,发起退款金额>item剩余可退金额;需要修改退款金额重新发起 |
22014 | 订单有其他退款申请正在进行中,不支持发起退款申请 | |
22015 | 订单状态不支持取消订单 |
Q&A
1.如何判断订单是否在退款中/已退款
**A:查询退款**接口用 order_id 查询退款信息,可以得知订单是否发生了退款以及退款状态
2.为什么一直处于退款中
A:查询退款接口用 refund_id 查询退款信息,首先看 refund_status 是不是退款中,如果是,则按以下步骤确认:
-
-
- out_refund_no为空,说明退款申请回调未成功,请开发者确认自身系统接入了退款申请回调且正确响应了退款申请回调。交易系统会持续重试,直到回调成功。排查方法请参考:退款申请回调文档末尾的退款申请回调接口排查模块
- out_refund_no不为空,则看审核状态audit_status,如果是待审核状态,请同步审核结果。
- 以上都不是,请联系oncall
-
3.如何判断退款单的审核状态
A:查询退款接口查询退款信息,merchant_audit_detail.audit_status 是审核状态,merchant_audit_detail.refund_audit_deadline 是审核的最后期限
4.商家未同步退款审核结果,为什么退款成功了
**A:**退款审核有最后期限,一般是 3 天(从发起退款的时刻开始),在退款申请回调/查询退款能获取到,商家需要在有效期内同步审核结果。有效期过后,系统将默认审核通过。
5.哪些退款单需要审核,哪些不需要审核
A:
[抖音客服发起退款]、[预约失败交易系统自动发起加价单退款]无需审核
用户发起、开发者发起、过期自动退、下单即预约且预约失败自动发起退款都需要审核
6.退款审核/退款查询接口报错,订单不存在是什么原因
A:按以下步骤进行排查
-
如果是刚刚发起退款,查询接口有时延,建议延迟几秒重试一下
-
如果已经发起退款很久了,建议调查询退款接口,
-
- 如果查询不到则说明单号不存在,请检查请求参数。
- 大多数情况下,开发者用 out_refund_no 来审核退款或查询退款时报错,都是因为 out_refund_no 不存在导致,建议检查一下是否已经成功发起退款或者是否正确响应了退款申请回调。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块
7.为什么开发者未发起退款,但是收到了退款申请回调/查询到订单处于退款中
A:除开发者发起外,还存在用户在退款组件发起、系统自动退款、抖音客服发起等场景,请通过查询退款接口查询订单的退款记录,并检查 refund_source 字段,可以获得具体的退款来源。
8.为什么订单会存在抖音客服发起的退款
A:用户找到抖音客服投诉,客服会联系商家确认后发起客服退款,如有疑问请咨询行业运营。客服退不需要商家审核,但需要开发者响应退款申请回调,客服退流程详见退款申请回调-接口说明模块的流程图。
curl --location --request POST 'http://dev-cn.your-api-server.com/api/apps/trade/v2/refund/create_refund' \
--header 'access-token: clt.xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"out_order_no": "123123131",
"out_refund_no": "123123",
"cp_extra": "extra_info",
"order_entry_schema": {
"path": "page/xxx",
"params": "{\"id\":1}"
},
"notify_url": "https://xxx",
"item_order_detail": [
{
"item_order_id": "xxx",
"refund_amount": 100
}
]
}'
{
"data": {
"refund_id": "ot12312312",
"refund_audit_deadline": 151231321231
},
"extra": {
"sub_error_code": 0,
"sub_description": "success",
"logid": "2022092115392201020812109511046",
"now": 1663745962686,
"error_code": 0,
"description": "success"
}
}