抖音开放平台Logo
控制台

发起退款

更新时间 2024-07-24 02:58:49
收藏
我的收藏

接口说明

  • 开发者通过本接口发起退款，支持整单退，部分退。
  • 一笔订单可以多次退款。微信渠道不超过 50 次，支付宝渠道不超过 300 次。
  • 交易时间超过 1 年的订单无法提交退款。
  • 申请退款接口的返回仅代表业务的受理情况，退款是否成功，可以接收退款通知或者退款查询接口主动获取。
  • 银行卡支付的退款 7 天内到账，支付宝支付（余额、银行卡快捷支付等）的退款 3 个工作日内到账，微信支付（余额、银行卡快捷支付等）的退款 7 天内到账。（退款优先原路退，如用户使用尾号为 1234 的招行借记卡付款，则退款至用户尾号为 1234 的招行借记卡）。
  • 开发者发起退款的业务流程如下

使用限制

接入前，请先查看接入前准备是否完成

基本信息

名称描述
HTTP URL
https://open.douyin.com/api/trade_basic/v1/developer/refund_create/
HTTP Method
POST
Scope
trade_basic.developer.trade_refund
权限要求

无

请求头

名称字段类型是否必填示例描述
access-tokenString是clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
调用https://open.douyin.com/oauth/client_token/生成的token
content-typeString是application/json
固定值"application/json"

请求参数

Body

名称字段类型是否必填示例描述
cp_extraString是extra_info
开发者自定义透传字段，不支持二进制，长度 <= 2048 byt>
order_idString是motb123123131
抖音开平侧订单号，长度 <= 64 byt>
out_refund_noString是123123
开发者侧退款单号，长度 <= 64 byt>
refund_total_amountInt64是100
退款总金额，单位分
notify_urlString否https://xxx

退款结果通知地址，必须是 HTTPS 类型， 长度 <= 512 byte 。若不填，则默认使用在解决方案配置-消息通知中指定的回调地址，配置方式参考解决方案配置文档

refund_allBool否

当订单未发生任何退款时，可设置refund_all=true，refund_total_amount=订单实付金额，发起整单退款。refund_all=true时不能设置item_order_detail

请求示例

curl --location --request POST 'https://open.douyin.com/api/trade_basic/v1/developer/refund_create/' \ 
--header 'Content-Type: application/json' \ 
--header 'access-token: clt.xxx' \ 
--data-raw='{ 
        "order_id": "motb123123131", 
        "out_refund_no": "ext_123123", 
        "cp_extra": "extra_info", 
        "order_entry_schema": { 
            "path": "page/xxx", 
            "params": "{\"id\":1}" 
        }, 
        "refund_total_amount ":100,
        "notify_url": "https://xxx", 
        "item_order_detail": [ 
                { 
                        "item_order_id": "xxx", 
                        "refund_amount": 100 
                } 
        ],
        "refund_reason":[{"code":101,"text":"不想要了"}] 
}'

响应参数

Body

名称字段类型是否必填示例描述
err_msgString是success

错误提示信息

err_noInt32是0

状态码 0 代表业务处理成功，具体错误码参见后文错误码章节

log_idString是2023010128382726

日志id，排查问题时使用

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "success",
  "log_id": "2022092115392201020812109511046",
  "data": {
    "refund_id": "motb7922312",
    "refund_audit_deadline": 151231321231
  }
}

异常响应示例

{
  "err_no": 10000,
  "err_msg": "参数不合法:refund_total_amount必须>0",
  "log_id": "2022092115392201020812109511046"
}

错误码

http状态码错误码错误码描述排查建议
20028001005
系统内部错误，请重试
请求重试，若依然无解请向平台提交反馈
20028001003
access_token无效
重新请求生成access_token
20028001008
access_token过期,请刷新或重新授权
重新请求生成access_token
20028001016
当前应用已被封禁或下线
clientKey被封禁或者下线
20028001006
网络调用错误，请重试
重试即可
20028001014
应用未授权任何能力
确认应用是否授权能力
20028001018
应用未获得该能力
开通相关能力
20028003017
quota已用完
联系平台处理
20028001019
应用该能力已被封禁
该能力被封禁，联系平台处理
20028001007
参数不合法
根据错误信息检查请求参数是否填写正常
20010000

参数不合法：xxx参数不合法/本接口不支持该类型订单发起退款/(ots72128388728472)商品单不存在

  • xxx参数不合法：对照错误提示和接口参数定义，检查对应的参数
  • 本接口不支持该类型订单发起退款：请检查order_id是否正确，交易系统订单请传入交易系统订单号，担保支付订单请传入担保交易单号
  • (ots72128388728472)商品单不存在：按以下步骤排查：
    • 1. 检查item_order_id是否正确，注意item_order_id是商品单
    • 2. 检查order_id与item_order_id是否匹配。用订单查询接口查询商户单下的所有商品单列表，检查item_order_id是否在列表中。
20012001

操作过于频繁，请稍后再试

稍后再试

20013000

系统错误，请重试

请重试，若多次重试仍然报错，请联系oncall

20020000

订单不存在

检查order_id是否正确，order_id与appid是否匹配，order_id与登录的用户是否匹配

20022000

订单状态不支持退款

请检查订单状态：订单未支付不允许发起退款

20022001

商品单(motb718283)状态xxx,不支持发起退款

商品单的状态是xxx，该状态下不允许发起退款

1. 退款中，需要等该笔退款完结后，才能再次发起

2. 履约中/已履约，请核对订单规则，确认此状态是否允许退款。

20022002

无可退款的商品单

订单下所有的item处于不可退状态时，无法发起退款，参考22001的说明

20022004

外部退款单号重复

开发者生成的外部退款单号以前已经用过了，请重新生成

20022007

退款的商品总数量超限

20022009

履约状态不同的商品单不能同时发起退款,请分别发起

商品单履约状态不一致，请分别发起(由于履约状态不一致的商品单资金状态可能不同，若同时发起可能导致卡单，所以建议分别发起)

20022012

退款来源不支持退款

退款来源有: 用户,开发者,抖音客服

20022013

退款金额不能大于实付金额/商品单(motb71263537)退款金额超过可退金额/CPS(motb72128284)商品单退款金额必须>=实付金额*n%

  • 退款金额不能大于实付金额：请修改退款金额
  • 商品单(motb71263537)退款金额超过可退金额：请修改退款金额
  • CPS(motb72128284)商品单退款金额必须>=实付金额*n%：CPS订单退款时，item单的退款金额必须>=实付的n%
​