抖音开放平台Logo
开发者文档
小程序
“/”唤起搜索
控制台
  • OpenAPI 简介
  • 通用参数
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 运营
  • 生活服务
  • 通用能力
  • 生活服务交易系统（全融合版）
  • 生活服务交易系统（账号融合版）
  • 错误码和返回码
  • 通用参数
  • 预约
  • 查询接口
  • 预下单
  • 营销算价
  • 支付
  • 核销
  • 分账
  • 退货退款
  • 发起退款
  • 同步退款审核结果
  • 查询退款
  • 退款申请回调
  • 通知退款结果
  • CPS佣金设置与查询
  • 即送（原随心团）解决方案
  • 核销工具解决方案
  • 历史版本（不推荐使用）
  • 垂直行业
  • 其它

    • 接口说明

    当开发者需要替用户发起退款时，可用该接口替用户发起退款。
      •一笔订单可以多次退款。微信渠道不超过 50 次，支付宝渠道不超过 300 次。
      •交易时间超过 1 年的订单无法提交退款。
      •银行卡支付的退款 7 天内到账，支付宝支付（余额、银行卡快捷支付等）的退款 3 个工作日内到账，微信支付（余额、银行卡快捷支付等）的退款 7 天内到账。（退款优先原路退，如用户使用尾号为 1234 的招行借记卡付款，则退款至用户尾号为 1234 的招行借记卡）。
      •预约类商品订单发起退款前，需确保预约单与主单均未处于退款处理中、退款完成状态。

    使用限制

    请不要滥用退款能力，如果发现滥用退款能力，平台会进行惩处。
    超时未接单会自动退，预约成功状态可发起退款（不支持预约中/待接单状态发起退款），可以调用查询预约单信息接口查询status字段判断预约单状态

    退款流程

    退款流程如下：

    过期自动退说明

      •过期自动退的退款被拒绝退款后，不会再次发起。
      •在交易系统产生的订单，如果用户购买的商品是过期退商品，在商品到达过期时间后，交易系统会自动发起退款，创建退款单，退款流程和用户发起退款流程相同。
      •发起过期自动退条件：
      ◦非 POI 商品：
      ▪前端传入合法的商品过期时间。
      ▪前端传入的 goodsLabels 中包含过期退标签。
      ◦POI 团购商品：
      ▪POI 商品设置了过期时间。
      ▪POI 商品的 sub_title 包含过期退标签。
      ◦担保支付不会自动发起过期自动退，仍需开发者处理。 过期自动退的退款单由系统创建，因此 退款申请回调和状态通知回调 cp_extra 会是空值。

    外部退款单号说明：

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

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

      •开发者发起退款，一次退款不能同时包含核销前和核销后的item_order，请分别发起核销前或核销后退款。
      •开发者发起退款，如果其中一个子单已经核销并且分账，另一个子单刚核销，刚核销的子单需要等待一个小时分账后再退款
      •核销满 30 天后不支持退款

    部分金额退功能说明

    在某些特殊的场景下（次卡、酒旅订单等），用户退 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
    https://open.douyin.com/api/apps/trade/v2/refund/create_refund
    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，确保每次传入的out_refund_no在开发者系统保证唯一
    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 参数详解
    refund_total_amount
    int64
    否
    退款总金额，单位分
      •担保交易订单必传
      •交易系统订单该字段不生效
    100
    refund_reasons
    Array<object>
    否
    退款信息
    详见下方 refund_reason 参数详解
    refund_description
    string
    否
    退款备注
    ​
    refund_all
    Bool
    否
    当订单未发生任何退款时，可设置refund_all=true，refund_total_amount=订单实付金额，发起整单退款。refund_all=true时不能设置item_order_detail
    true
    fee_detail
    Array<object>
    否
    仅航司小程序使用
    详见下方 fee_detail 参数详解

    order_entry_schema 信息

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

    item_order_detail 信息

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

    fee_detail 信息

    名称
    类型
    是否必填
    描述
    示例
    fee_type
    int
    是
    // 基建费
    FeeType = 18
    // 燃油费
    FeeType = 19
    // 税费
    FeeType = 20
    18
    refund_amount
    int64
    是
    fee 退款金额
    100
    ​

    refund_reason 信息

    名称
    类型
    是否必填
    描述
    示例
    code
    int64
    是
    退款编码
    详见下方 退款编码 详解

    编码列表

    退款编码
    含义
    102
    没看清使用规则，要用时才发现有限制
    103
    其他平台/方式购买更优惠
    106
    商家营业但不接待
    107
    商家停业/装修/转让
    109
    朋友/网上评价不好
    114
    不能送外卖
    116
    可用的门店距离太远
    117
    担心安全问题（疫情、天气等）
    118
    需要加价/购买其他产品才能用
    119
    服务态度不好
    122
    实际与宣传/描述不一样
    123
    商家服务态度差
    125
    商家要求改用其他方式/平台付款
    158
    电话/发消息联系不上商家
    161
    排队太久/预约不上位置、包厢等
    211
    商家餐品有质量问题
    212
    商家地址信息错误,找不到店铺
    213
    不满足使用条件
    215
    因排队等原因放弃使用
    217
    商家设备/环境有质量问题
    304
    因疫情/天气等不可抗力无法使用
    305
    个人原因无法到店使用
    306
    券被错误核销
    401
    计划有变，暂时不需要了
    402
    买多了/买错了
    406
    商家缺货
    999
    其他原因（需填写备注）

    请求示例

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

    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)商品单不存在
    按以下步骤排查：
      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变为已核销状态后，再发起退款
      3.次卡类型，若所有次数均已核销则不允许退款
    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_id 查询退款信息，首先看 refund_status 是不是退款中，如果是，则按以下步骤确认：
      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.商家未同步退款审核结果，为什么退款成功了

    A：退款审核有最后期限，一般是 3 天(从发起退款的时刻开始)，在退款申请回调/查询退款能获取到，商家需要在有效期内同步审核结果。有效期过后，系统将默认审核通过。

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

    A：
    [抖音客服发起退款]、[预约失败交易系统自动发起加价单退款]无需审核。
    用户发起、开发者发起、过期自动退、下单即预约且预约失败自动发起退款都需要审核。

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

    A：按以下步骤进行排查：
      1.如果是刚刚发起退款，查询接口有时延，建议延迟几秒重试一下。
      2.如果已经发起退款很久了，建议调查询退款接口。
      a.如果查询不到则说明单号不存在，请检查请求参数。
      b.大多数情况下，开发者用 out_refund_no 来审核退款或查询退款时报错，都是因为 out_refund_no 不存在导致，建议检查一下是否已经成功发起退款或者是否正确响应了退款申请回调。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块

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

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

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

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