开发者发起退款
收藏
我的收藏

当开发者需要替用户发起退款时，可用该接口替用户发起退款。

使用限制

请不要滥用退款能力，如果发现滥用退款能力，平台会进行惩处。

接口说明

•

一笔订单可以多次退款。微信渠道不超过 50 次，支付宝渠道不超过 300 次。

•

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

•

申请退款接口的返回仅代表业务的受理情况，退款是否成功，可以接收退款通知或者退款查询接口主动获取。

•

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

退款流程

退款流程如下：

过期自动退说明

•

过期自动退的退款被拒绝退款后，不会再次发起。

•

在交易系统产生的订单，如果用户购买的商品是过期退商品，交易系统会自动发起退款，创建退款单，退款流程和用户发起退款流程相同。

•

发起过期自动退条件：

◦

非 POI 商品：

▪

前端传入合法的商品过期时间。

▪

前端传入的 goodsLabels 中包含过期退标签。

◦

POI 团购商品：

▪

POI 商品设置了过期时间。

▪

POI 商品的 sub_title 包含过期退标签。

◦

担保支付不会自动发起过期自动退，仍需开发者处理。过期自动退的退款单由系统创建，因此退款申请回调和状态通知回调 cp_extra 会是空值。

外部退款单号说明

•

外部退款单号务必确保在同一小程序内不会重复

未核销/已核销的 item 需要分开发起退款

•

开发者发起退款，一次退款不能同时包含核销前和核销后的item_order，请分别发起核销前或核销后退款。

部分金额退功能说明

在某些特殊的场景下（次卡、酒旅订单等），用户退 item_order 的退款金额不等于实付金额，开发者需要指定用户退款的 item_order 的退款金额（退款 item_order 部分金额）。交易系统也支持了该特殊场景，允许开发者在前端组件和开发者发起退款的 Open API 指定 item_order 退款金额。

开发者需要使用部分金额退功能，请联系对应的行业运营开通。

若不指定 item_order 退款金额，则和普通退款（退实付金额）相同。

如果该 item_order 已经退款成功，不能再发起退款。不支持已退款成功的 item_order，再发起退款。

次卡退款说明

次卡仅支持开发者用openAPI发起退款，开发者必须指定item_order和对应的退款金额

次卡仅支持退剩余未核销金额，已核销的金额不支持退款

次卡仅允许退款一次，即如果次卡已退款成功则无法再次发起退款

次卡不支持过期自动退

基本信息

基本信息
HTTP URL	https://developer.toutiao.com/api/apps/trade/v2/create_refund
HTTP Method	POST
权限要求	无

请求头

名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"
Byte-Authorization	string	是	请参见签名算法

请求参数

名称	类型	是否必填	描述	示例值
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 类型，若不填，默认使用在抖音开放平台-小程序应用详情-能力-支付页面设置的支付回调地址。长度 <= 512 byte	https://xxx
item_order_detail	`Array<object>`	否	需要发起退款的商品单信息，数组长度<100 注意：交易系统订单必传	详见下方 item_order_detail 参数详解
refund_total_amount	`int64`	否	退款总金额，单位分 •担保交易订单必传 •交易系统订单不能传该字段	100

order_entry_schema 信息

名称	类型	是否必填	描述	示例值
path	`string`	是	订单详情页路径，没有前导的/，该字段不能为空，长度 <= 512byte	pages/indexxxx
params	`string`	否	路径参数，自定义的 json 结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问订单详情的 schema 能正确跳转到小程序内部的订单详情页，长度 <= 512byte	{\"id\":\"xxxxxx\"}

item_order_detail 信息

名称	类型	是否必填	描述	示例
item_order_id	`string`	是	商品单号，参见通用参数-重要 ID 字段说明	ot7072366682238
refund_amount	`int64`	否	该 item_order 需要退款的金额，单位分，不能大于该 item_order 实付金额且要大于 0 需要指定 item_order 的退款金额，需要申请开通指定金额退款权限才能使用	100

请求示例

交易系统订单退款请求示例

curl --location --request POST 'https://developer.toutiao.com/api/apps/trade/v2/create_refund' \
--header 'Content-Type: application/json' \
--header 'Byte-Authorization: SHA256-RSA2048 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="'
--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://developer.toutiao.com/api/apps/trade/v2/create_refund?access_token=abcdefg×tamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' \
--header 'Byte-Authorization: SHA256-RSA2048 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="'
--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
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	`int64`	是	状态码 0 代表业务处理成功，具体错误码参见后文错误码章节	0
err_tips	`string`	是	错误提示信息	success
data	`object`	否	返回数据信息	success

data 信息

名称	类型	是否必填	参数描述	示例值
refund_id	`string`	是	抖音开放平台交易系统内部退款单号	ot12312312
refund_audit_deadline	`int64`	是	退款审核的最后期限，13 位 unix 时间戳，精度：毫秒通常是3天(从退款发起时间开始算)	151231321231

响应示例

正常示例

{
  "err_no": 0,
  "err_tips": "success",
  "data": {
    "refund_id": "ot12312312",
    "refund_audit_deadline": 151231321231 
  }
}

正常示例

{
  "err_no": 13000,
  "err_tips": "系统错误" 
 }

错误码

详情参见错误码/返回码。

错误码	错误提示	建议解决方案
10000	参数不合法：(ots72128388728472)商品单不存在	按以下步骤排查： 1.检查item_order_id是否正确，注意是item_order_id，不是商户单id 2.检查out_order_no与item_order_id是否匹配。用查询券状态接口查询商户单下的所有item列表，检查item_order_id是否在列表中。
11001	访问未授权	退款金额小于实付金额的被判断为部分退款，需要申请权限，请联系行业运营
20000	订单不存在	检查out_order_no是否正确，out_order_id与appid是否匹配
22000	订单状态不支持退款	请检查订单状态：订单未支付或已关闭则不允许再发起退款
22001	(ots7218277338394847)商品单状态不支持退款	订单item子单的状态不允许发起退款，用查询券状态接口查询item单的状态： 1.item处于[退款中,退款完成]状态时，不允许退款 2.预约类的item，处于[退款中,退款完成,预约中]状态时不允许退款。 a.下单即预约(门票)的item，预约中不允许退款，可以取消预约后发起退款 b.先买后约(预售券)的item，预约中/预约成功状态不允许退款，可以取消预约或者等预约完成时间过后，item变为已核销状态后，再发起退款
22002	无可退款的商品单	订单下所有的item处于不可退状态时，无法发起退款，参考22001的说明
22004	外部退款单号重复了	开发者生成的外部退款单号以前已经用过了，请重新生成
22006	退款单状态不允许设置商家审核结果	退款审核状态前置步骤未完成，等几分钟后再重新发起
22007	超出单次最大可退款的商品数量	一般是单次退款item订单的数量超过了100
22008	退款商品数量超过可退款的商品数量	用户可以发起退款的item单数小于请求数
22009	不支持同时发起核销前和核销后退款	发起退款的item单列表中包含已核销和未核销的，需要分别发起退款
22010	只允许整单退款，请发起整单退款	门票、下单即预约场景，订单只允许整单退
22011	加价单不允许发起退款	预约失败时加价单会自动发起退款，不允许开发者发起退款。
22012	退款来源不支持退款	退款来源有: 用户,开发者
22013	退款金额不符合条件，提交退款失败	几种可能的场景： 1.次卡类型，发起退款金额 > 剩余未核销金额；需要修改退款金额重新发起 2.外卖类型，发起退款金额 > 剩余可退金额；需要修改退款金额重新发起 3.小程序开通了item多次退白名单，发起退款金额>item剩余可退金额；需要修改退款金额重新发起
22014	订单有其他退款申请正在进行中，不支持发起退款申请
22015	订单状态不支持取消订单

Q&A

1.如何判断订单是否在退款中/已退款

**A：查询退款**接口用 order_id 查询退款信息，可以得知订单是否发生了退款以及退款状态

2.为什么一直处于退款中

**A：查询退款**接口查询退款信息，首先看 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：按以下步骤进行排查

如果是刚刚发起退款，查询接口有时延，建议延迟几秒重试一下

如果已经发起退款很久了，建议查询退款，

a. 如果查询不到则说明单号不存在，请检查请求参数。

b. 大多数情况下，开发者用 out_refund_no 来审核退款或查询退款时报错，都是因为 out_refund_no 不存在导致，建议检查一下是否已经成功发起退款或者是否正确响应了退款申请回调。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块

7.为什么开发者未发起退款，但是收到了退款申请回调/查询到订单处于退款中

A：除开发者发起外，还存在用户在退款组件发起、系统自动退款、抖音客服发起等场景，请通过查询退款接口查询订单的退款记录，并检查 refund_source 字段，可以获得具体的退款来源。

8.为什么订单会存在抖音客服发起的退款

A：用户找到抖音客服投诉，客服会联系商家确认后发起客服退款，如有疑问请咨询行业运营。客服退不需要商家审核，但需要开发者响应退款申请回调，客服退流程详见退款申请回调-接口说明模块的流程图。

开发者发起退款收藏我的收藏

​使用限制​

​接口说明​

​退款流程​

​过期自动退说明​

​外部退款单号说明​

​未核销/已核销的 item 需要分开发起退款​

​部分金额退功能说明​

​次卡退款说明​

​基本信息​

​请求头​

​请求参数​

​order_entry_schema 信息​

​item_order_detail 信息​

​请求示例​

​交易系统订单退款请求示例​

​担保交易退款请求示例​

​响应参数​

​data 信息​

​响应示例​

​正常示例​

​正常示例​

​错误码​

​Q&A​

​1.如何判断订单是否在退款中/已退款​

​2.为什么一直处于退款中​

​3.如何判断退款单的审核状态​

​4.商家未同步退款审核结果，为什么退款成功了​

​5.哪些退款单需要审核，哪些不需要审核​

​6.退款审核/退款查询接口报错，订单不存在是什么原因​

​7.为什么开发者未发起退款，但是收到了退款申请回调/查询到订单处于退款中​

​8.为什么订单会存在抖音客服发起的退款​

开发者发起退款
收藏
我的收藏

使用限制

接口说明

退款流程

过期自动退说明

外部退款单号说明

未核销/已核销的 item 需要分开发起退款

部分金额退功能说明

次卡退款说明

基本信息

请求头

请求参数

order_entry_schema 信息

item_order_detail 信息

请求示例

交易系统订单退款请求示例

担保交易退款请求示例

响应参数

data 信息

响应示例

正常示例

正常示例

错误码

Q&A

1.如何判断订单是否在退款中/已退款

2.为什么一直处于退款中

3.如何判断退款单的审核状态

4.商家未同步退款审核结果，为什么退款成功了

5.哪些退款单需要审核，哪些不需要审核

6.退款审核/退款查询接口报错，订单不存在是什么原因

7.为什么开发者未发起退款，但是收到了退款申请回调/查询到订单处于退款中

8.为什么订单会存在抖音客服发起的退款