开发者发起退款

更新时间 2024-07-24 02:58:49

我的收藏

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

使用限制

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

接口说明

•

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

•

交易时间超过30天的订单无法提交退款。

•

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

•

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

退款流程

退款流程如下：

退款说明

•

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

•

发起过期自动退条件：

◦

POI 团购商品：

▪

POI 商品设置了过期时间。

•

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

•

外部退款单号说明：

◦

已经在担保支付或者交易 1.0 使用过的外部退款单号，请不要在交易系统使用，当交易系统发现该外部退款单号已经在担保支付或者交易 1.0 创建过退款单号时，会拒绝创建退款单。

•

开发者发起的退款不需要退款审核，不需要调用同步退款审核结果 接口。

•

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

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/apps/trade/v2/refund/create_refund
HTTP Method	POST
Scope	industry_open.trade.refund
权限要求	不需要用户授权

请求头

名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"
access-token	string	是	调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
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`	否	退款结果通知地址。此地址在接入流程-行业模版使用指南-消息通知中设置。长度 <=512byte	https://xxx
item_order_detail	`Array<object>`	是	需要发起退款的商品单信息，数组长度<100	详见下方 item_order_detail 参数详解
times_card_refund_param	object	否	次卡退款必填	详见下方 times_card_refund_param 参数详解

order_entry_schema 信息

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

item_order_detail 信息

名称	类型	是否必填	描述	示例
item_order_id	`string`	是	商品单号，参见通用参数-重要 ID 字段说明	ot7072366682238

times_card_refund_param 信息

名称	类型	是否必填	描述	示例
times_card_refund_type	int64	是	次卡退款类型,1-退剩余次数,2-全部退	1

请求示例

js复制
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"
                }
        ],
        "times_card_refund_param":{
            "times_card_refund_type": 1
        }
}'

响应参数

名称	类型	是否必填	描述	示例值
data	`object`	否	返回数据信息
extra	object	是	额外信息，参考通用参数中的说明

data 信息

名称	类型	是否必填	参数描述	示例值
error_code	int	是	错误码，0为成功	0
description	string	是	错误码描述	success
refund_id	`string`	是	抖音开放平台交易系统内部退款单号	ot12312312

响应示例

正常示例

json复制
{
  "data": {
    "error_code": 0,
    "description": "success",
    "refund_id": "ot12312312"
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

json复制
{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

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

错误码	错误提示	建议解决方案
10000	参数不合法：(ots72128388728472)商品单不存在	按以下步骤排查： 1.检查item_order_id是否正确，注意是item_order_id，不是商户单id 2.检查out_order_no与item_order_id是否匹配。用查询券状态接口查询商户单下的所有item列表，检查item_order_id是否在列表中。
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单列表中包含已核销和未核销的，需要分别发起退款
22012	退款来源不支持退款	退款来源有: 用户,开发者
22014	订单有其他退款申请正在进行中，不支持发起退款申请