发起退款
收藏当开发者需要替用户发起退款时，可用该接口替用户发起退款。
使用限制
请不要滥用退款能力，如果发现滥用退款能力，平台会进行惩处。
接口说明
- •一笔订单可以多次退款。微信渠道不超过 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 退款金额。
开发者需要使用部分金额退功能，请联系对应的行业运营开通。
- 1.若未指定 item_order 退款金额，则 和 普通退款（退实付金额）相同。
- 2.如果该 item_order 已经退款成功，不能再发起退款。不支持已退款成功的 item_order，再发起退款。
次卡退款说明
- 1.次卡仅支持开发者用openAPI发起退款，开发者必须指定item_order和对应的退款金额
- 2.次卡仅支持退剩余未核销金额，已核销的金额不支持退款。如果次卡的所有次数均已核销，则不支持发起退款。
- 3.次卡仅允许退款一次，即如果次卡已退款成功则无法再次发起退款
- 4.次卡不支持过期自动退
基本信息
基本信息 | |
HTTP URL | |
HTTP Method | POST |
Scope | industry_open.trade.refund |
权限要求 | 不需要用户授权 |
请求头
请求参数
对于历史上没有接入过“担保支付”和“交易模板 1.0”两个系统的开发者可以忽略“旧系统”这个概念
- •新系统订单退款，必传item_order_detail字段
- •旧系统订单退款，必传refund_total_amount，(旧系统是指通过担保交易和旧交易模板产生的订单)
- •item_order_detail 和 refund_total_amount 不能同时传入
- •通过开发者接口发起退款，请注意 item_order 的状态（待使用和已核销可以发起退款，其他状态无法发起退款）
- •用户发起退款，只有 item_order 的状态为待使用状态才可以发起退款
- •开发者发起退款和用户发起退款、过期自动退都需要退款审核，需要调用
退款审核结果同步 接口同步同意退款还是拒绝退款。名称 | 类型 | 是否必填 | 描述 | 示例值 |
out_order_no | string | 是 | 开发者侧订单号，长度 <= 64 byte | 123123131 |
out_refund_no | string | 是 | 开发者侧退款单号，长度 <= 64 byte | 123123 |
cp_extra | string | 否 | 开发者自定义透传字段，不支持二进制，长度 <= 2048 byte | extra_info |
order_entry_schema | object | 是 | 退款单的跳转的 schema | 详见下方 order_entry_schema 参数详解 |
notify_url | string | 否 | https://xxx | |
item_order_detail | Array<object> | 否 | 需要发起退款的商品单信息，数组长度<100 注意：交易系统订单必传 | 详见下方 item_order_detail 参数详解 |
refund_total_amount | int64 | 否 | 退款总金额，单位分
| 100 |
order_entry_schema 信息
名称 | 类型 | 是否必填 | 描述 | 示例值 |
path | string | 是 | 订单详情页路径， 没有前导的/，该字段不能为空，长度 <= 512byte | pages/indexx |
params | string | 否 | 路径参数，自定义的 json 结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问订单详情的 schema 能正确跳转到小程序内部的订单详情页，长度 <= 512byte | {\"id\":\"cx\"} |
item_order_detail 信息
名称 | 类型 | 是否必填 | 描述 | 示例 |
item_order_id | string | 是 | ot7072366682238 | |
refund_amount | int64 | 否 | 该 item_order 需要退款的金额，单位分，不能大于该 item_order 实付金额且要大于 0 需要指定 item_order 的退款金额，需要申请开通指定金额退款权限才能使用 | 100 |
请求示例
交易系统订单退款请求示例
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", "item_order_detail": [ { "item_order_id": "xxx", "refund_amount": 100 } ] }'
担保交易、旧交易系统订单退款的请求示例
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 }'
响应参数
名称 | 类型 | 是否必填 | 描述 | 示例值 |
data | object | 否 | 返回数据信息 | success |
extra | object | 是 | 额外信息，参考通用参数中的说明 | |
data 信息
名称 | 类型 | 是否必填 | 参数描述 | 示例值 |
refund_id | string | 是 | 抖音开放平台交易系统内部退款单号 | ot12312312 |
refund_audit_deadline | int64 | 是 | 退款审核的最后期限，13 位 unix 时间戳，精度：毫秒 通常是3天(从退款发起时间开始算) | 151231321231 |
响应示例
正常示例
{ "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" } }
异常示例
{ "data": { "error_code": 13000, "description": "系统错误" }, "extra": { "sub_error_code": 13000, "sub_description": "系统错误", "logid": "2022092115392201020812109511046", "now": 1663745962686, "error_code": 2191000, "description": "" }
错误码
错误码 | 错误提示 | 建议解决方案 |
10000 | 参数不合法：(ots72128388728472)商品单不存在 | 按以下步骤排查：
|
11001 | 访问未授权 | 退款金额小于实付金额的被判断为部分退款，需要申请权限，请联系行业运营 |
20000 | 订单不存在 | 检查out_order_no是否正确，out_order_id与appid是否匹配 |
22000 | 订单状态不支持退款 | 订单未支付或已关闭则不允许再发起退款 |
22001 | (ots7218277338394847)商品单状态不支持退款 |
|
22002 | 无可退款的商品单 | 订单下所有的item处于不可退状态时，无法发起退款，参考22001的说明 |
22004 | 外部退款单号重复了 | 开发者生成的外部退款单号以前已经用过了，请重新生成 |
22006 | 退款单状态不允许设置商家审核结果 | 退款审核状态前置步骤未完成，等几分钟后再重新发起 |
22007 | 超出单次最大可退款的商品数量 | 一般是单次退款item订单的数量超过了100 |
22008 | 退款商品数量超过可退款的商品数量 | 用户可以发起退款的item单数小于请求数 |
22009 | 不支持同时发起核销前和核销后退款 | 发起退款的item单列表中包含已核销和未核销的，需要分别发起退款 |
22010 | 只允许整单退款，请发起整单退款 | 门票、下单即预约场景，订单只允许整单退 |
22011 | 加价单不允许发起退款 | 预约失败时加价单会自动发起退款，不允许开发者发起退款。 |
22012 | 退款来源不支持退款 | 退款来源有: 用户,开发者 |
22013 | 退款金额不符合条件，提交退款失败 | 几种可能的场景：
|
22014 | 订单有其他退款申请正在进行中，不支持发起退款申请 | |
22015 | 订单状态不支持取消订单 | |
Q&A
1.如何判断订单是否在退款中/已退款
2.为什么一直处于退款中
- a.out_refund_no为空，说明退款申请回调未成功，请开发者确认自身系统接入了退款申请回调且正确响应了退款申请回调。交易系统会持续重试，直到回调成功。排查方法请参考：退款申请回调文档末尾的退款申请回调接口排查模块
- b.out_refund_no不为空，则看审核状态audit_status，如果是待审核状态，请同步审核结果。
- c.以上都不是，请联系oncall
3.如何判断退款单的审核状态
A：查询退款接口查询退款信息，merchant_audit_detail.audit_status 是审核状态，merchant_audit_detail.refund_audit_deadline 是审核的最后期限。
4.商家未同步退款审核结果，为什么退款成功了
5.哪些退款单需要审核，哪些不需要审核
A：
[抖音客服发起退款]、[预约失败交易系统自动发起加价单退款]无需审核。
用户发起、开发者发起、过期自动退、下单即预约且预约失败自动发起退款都需要审核。
6.退款审核/退款查询接口报错，订单不存在是什么原因
A：按以下步骤进行排查：
- 1.如果是刚刚发起退款，查询接口有时延，建议延迟几秒重试一下。
- 2.如果已经发起退款很久了，建议调查询退款接口。
- a.如果查询不到则说明单号不存在，请检查请求参数。
- b.大多数情况下，开发者用 out_refund_no 来审核退款或查询退款时报错，都是因为 out_refund_no 不存在导致，建议检查一下是否已经成功发起退款或者是否正确响应了退款申请回调。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块
7.为什么开发者未发起退款，但是收到了退款申请回调/查询到订单处于退款中
8.为什么订单会存在抖音客服发起的退款
