抖音开放平台Logo
开发者文档
小程序
“/”唤起搜索
控制台
  • OpenAPI 简介
  • 通用参数
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 评价
  • 交易工具
  • 交易系统
  • 通用交易系统
  • 行业交易系统
  • API 调用
  • 回调设置
  • 预下单
  • 营销算价
  • 支付
  • 核销
  • 分账
  • 退货退款
  • 开发者发起退款
  • 同步退款审核结果
  • 查询退款
  • 退款申请回调
  • 通知退款结果
  • 担保支付（即将下线）
  • 抖店绑定
  • 运营
  • 生活服务
  • 垂直行业
  • 其它
    • 开发者可通过此接口查询退款单的详情。适用场景举例：查询是否发起退款，查询退款单状态。

    使用限制

    无

    接口说明

      •支持 refund_id 查询
      •支持 out_refund_no 查询
      •支持 order_id 查询

    基本信息

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

    请求头

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

    请求参数

    注意：
      1.refund_id , out_refund_no , order_id 三选一，不能都不选。
      2.order_id维度的不兼容老退款单查询，只支持查询交易系统的退款。查询返回的结果数限制50条
    名称
    类型
    是否必填
    描述
    示例值
    refund_id
    string
    否
    抖音开平内部交易退款单号，长度 <= 64byte
    ot1231231
    out_refund_no
    string
    否
    开发者系统生成的退款单号，长度 <= 64byte
    12313
    order_id
    string
    否
    抖音开平内部交易订单号， 长度 <= 64byte
    ot7231231

    请求示例

    curl --location --request POST 'https://developer.toutiao.com/api/apps/trade/v2/query_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='{
        "refund_id": "ot1231231", //当有refund_id时，优先使用refund_id查询
        "out_refund_no": "12313"
}'

    响应参数

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

    data 信息

    名称
    类型
    是否必填
    描述
    示例
    refund_list
    Array<object>
    是
    退款查询结果列表，最多返回50条
    (建议开发者用这个字段)
    ​

    refund_list 说明

    名称
    类型
    是否必填
    描述
    示例
    refund_id
    string
    是
    系统退款单号，开放平台生成的退款单号
    ot13213
    out_refund_no
    string
    否
    开发者系统生成的退款单号，与抖音开平退款单号 refund_id 唯一关联
    2313
    refund_total_amount
    int64
    是
    退款金额，单位[分]
    100
    refund_status
    string
    是
    退款状态
    退款中- PROCESSING
    已退款- SUCCESS
    退款失败- FAIL
    PROCESSING
    refund_at
    int64
    否
    退款时间，13 位毫秒时间戳，只有已退款才有退款时间
    1643009622000
    message
    string
    否
    退款结果信息，非商家拒绝退款导致的退款失败，可以通过该字段了解退款失败原因
    退款失败
    order_id
    string
    是
    系统订单信息，开放平台生成的订单号
    ot123123
    item_order_detail
    Array<object>
    否
    商品单信息 (交易系统订单退款才有的信息)
    ​
    fee_order_detail
    Array<object>
    否
    fee
    ​
    merchant_audit_detail
    object
    否
    退款审核信息 (交易系统订单退款才有的信息)
    ​
    create_at
    int64
    是
    退款创建时间，13 位毫秒时间戳
    1643009622000
    refund_source
    int64
    否
    退款来源，仅交易2.0退款有来源，老的担保交易/1.0订单可能没有记录来源
    1: 用户发起退款
    2: 开放者发起退款
    3: 自动退款
    4: 抖音客服退款
    5: 预约失败自动发起退款
    6: 开发者拒绝接单退款
    7: 后约单触发先买单退款
    1

    item_order_detail 说明

    名称
    类型
    是否必填
    描述
    示例值
    item_order_id
    string
    是
    抖音开平侧的商品单号
    ot123123
    refund_amount
    int64
    是
    该商品单退款金额，单位[分]
    50

    merchant_audit_detail 说明

    名称
    类型
    是否必填
    描述
    示例
    refund_audit_deadline
    int64
    是
    退款审核的最后期限，过期无需审核，自动退款，13 位 unix 时间戳，精度：毫秒
    151231321231
    audit_status
    string
    是
    退款审核状态：
      •INIT：初始化
      •TOAUDIT：待审核
      •AGREE：同意
      •DENY：拒绝
      •OVERTIME：超时未审核自动同意
    AGREE
    deny_message
    string
    否
    不同意退款信息，长度 <= 512 byte
    不同意退款

    fee_order_detail说明

    名称
    类型
    是否必填
    描述
    示例
    fee_type
    string
    是
    类型
    FeeType_Infrastructure = 18 // 基建费
    FeeType_Fuel = 19 // 燃油费
    FeeType_Tax = 20 // 税费
    ​
    refund_amount
    int64
    是
    金额
    ​
    ​

    响应示例

    正常示例

      •由于旧协议没有兼容退款结果列表，所以新增了refund_list字段，建议开发者使用refund_list字段
    {
  "data": {
    "refund_list": [
      {
        "refund_at": 1672994501000,
        "create_at": 1672994428929,
        "refund_source": 1,
        "refund_total_amount": 1992,
        "refund_status": "SUCCESS",
        "out_refund_no": "ext_refund_no_718536707992153502030519534",
        "message": "",
        "item_order_detail": [
          {
            "item_order_id": "800000000101757849613437984",
            "refund_amount": 996
          },
          {
            "item_order_id": "800000000101757824013547984",
            "refund_amount": 996
          }
        ],
        "merchant_audit_detail": {
          "audit_status": "AGREE",
          "deny_message": "",
          "need_refund_audit": 1,
          "refund_audit_deadline": 1673253628929
        },
        "order_id": "8000000001017577984",
        "refund_id": "718536707992153502030519534"
      }
    ]
  },
  "resp_extra": {
    "logid": "02168173448144300000000000000000000ffff0a99604dfab9fd"
  },
  "err_no": 0,
  "err_tips": "success"
}

    异常示例

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

    错误码

    详情参见错误码/返回码 。
    错误码
    错误提示
    建议解决方案
    20000
    订单不存在
    按以下步骤进行排查：
      1.若刚刚发起退款，系统有延迟，建议等几秒钟再重试
      2.请仔细核对参数，out_refund_no、refund_id、order_id与app_id是否匹配
      3.如果是以refund_id、order_id查询，说明没有对应的退款单。
      4.如果是以out_refund_no查询，很可能是out_refund_no不存在。建议改用order_id查询退款，确认是否存在退款单。
      a.如果不存在退款单，说明没有成功发起退款。
      b.如果存在退款单且out_refund_no为空，说明开发者未响应退款申请回调。建议检查退款申请回调接口。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块
    ​
    以上步骤都排查过，仍然无法处理时请提oncall

    1.为什么开发者未发起退款，但是查询到订单在退款中？

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

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

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