抖音开放平台Logo
开发者文档
小程序
控制台
  • OpenAPI 简介
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 交易系统
  • 行业交易系统
  • 通用交易系统
  • 退款
  • 发起退款
  • 查询退款
  • 同步退款审核结果
  • 退款申请回调扩展点
  • 退款结果通知
  • 结算
  • 履约
  • 订单
  • 标签
  • 通用参数
  • 进件
  • 提现
  • 获取对账单
  • 担保支付（即将下线）
  • 评价
  • 抖店绑定
  • 交易工具
  • 运营
  • 生活服务
  • 垂直行业
  • 其它

    • 使用限制

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

    接口说明

      •由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。
      •回调可能存在延时，开发者可以主动请求查询退款接口获取退款状态。
      •在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败进行重试。
      •结果通知失败的重试间隔为：10s/10s/30s/1m/2m/3m/4m/5m/6m/7m/8m，一共重试10次。
    ​

    基本信息

    基本信息
    HTTP URL
    在解决方案配置-消息通知中指定的回调地址，配置方式参考解决方案配置文档
    HTTP Method
    POST
    权限要求
    无

    请求头

    参见通用参数-平台请求开发者公共参数。

    请求参数

    名称
    类型
    是否必填
    描述
    示例值
    msg
    string
    是
    订单相关信息的 JSON 字符串
    见下文示例
    type
    string
    是
    枚举值 refund：退款成功/退款失败
    refund
    version
    string
    是
    固定值："3.0"。回调版本，用于开发者识别回调参数的变更
    3.0
    ​
    msg 字段：
    名称
    类型
    是否必填
    描述
    示例值
    app_id
    string
    是
    小程序 id
    ttcfdbb0e33350
    status
    string
    是
    退款状态枚举值：SUCCESS：退款成功FAIL：退款失败
    SUCCESS
    order_id
    string
    是
    抖音开平侧订单号
    motb7057980663048
    refund_id
    string
    是
    抖音开平侧退款单号
    motb7014925531429
    refund_item_detail
    Json Object
    是
    退款商品单信息
    ​
    out_refund_no
    string
    是
    开发者自定义的退款单号（可能为空)
    530402398023
    cp_extra
    string
    是
    退款时开发者传入字段
    test
    refund_total_amount
    int64
    是
    退款金额，单位分
    9900
    refund_user_total_amount
    int64
    是
    有抖音营销的情况下，退用户的金额，单位分（无抖音营销时该值和refund_total_amount相同）
    9900
    is_all_settled
    bool
    是
    是否为分账后退款
    FALSE
    event_time
    int64
    是
    退款时间戳，单位为毫秒
    1643189272388
    message
    string
    否
    结果描述信息，如失败原因
    余额不足
    refund_type
    int64
    否
    退款来源类型，枚举值：
    1: 用户发起
    2：开发者发起
    4：抖音客服退款
    1
    ​
    refund_item_detail 字段：
    名称
    类型
    是否必填
    描述
    示例值
    item_order_quantity
    int64
    是
    用户退款商品单数量
    3
    item_order_detail
    array<object>
    是
    本次退款的商品单
    ​
    ​
    item_order_detail 字段：
    名称
    类型
    是否必填
    描述
    示例值
    item_order_id
    string
    是
    抖音开平侧商品单id
    motb75515980663048
    refund_amount
    int64
    是
    该商品单退款金额，单位[分]
    3300
    ​

    请求示例

    curl --location --request POST 'https://xxxxxxx.net/api/v2/result_callback?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json'
--data-raw='{
  "version": "3.0", //本次固定为3.0, 通过版本信息识别，用不同的结构体去解析上述关键参数
  "msg": "{\"app_id\":\"ttcfdbb96650e33350\",\"status\":\"SUCCESS\",\"order_id\":\"motb7057980663048\",\"cp_extra\":\"\",\"message\":\"\",\"event_time\":1643185934447,\"refund_id\":\"motb7014925531429\",\"out_refund_no\":\"530402398023\",\"refund_total_amount\":1,\"is_all_settled\":false,\"refund_item_detail\":{\"item_order_quantity\":1,\"item_order_detail\":[{\"refund_amount\":1,\"item_order_id\":\"motb75515980663048\"}]}}",
  "type": "refund"
}'
    ​
    msg 字段内容示例：
    //退款成功回调示例
{
    "app_id": "ttcfdbb96650e33350",
    "status": "SUCCESS",
    "order_id": "motb7057980663048",
    "cp_extra": "",
    "message": "",
    "event_time": 1643185934447,
    "refund_id": "motb7014925531429",
    "out_refund_no": "530402398023",
    "refund_total_amount": 1,
    "refund_user_total_amount": 1,
    "is_all_settled": false,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "motb75515980663048"
            }]
    }
}


//退款失败回调示例
{
    "app_id": "ttcfdbb96650e33350",
    "status": "FAIL",
    "order_id": "motb7057980663048",
    "cp_extra": "xxxxx",
    "message": "余额不足",
    "event_time": 1643185934447,
    "refund_id": "motb7014925531429",
    "out_refund_no": "ext_order_no_1643185898403",
    "refund_total_amount": 1,
    "refund_user_total_amount": 1,
    "is_all_settled": true,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "motb75515980663048"
            }]
    }
}
    ​

    响应参数

    名称
    类型
    描述
    示例值
    err_no
    int64
    错误码
    0
    err_tips
    string
    错误提示
    success
    ​

    响应示例

    ​

    正常示例

    //正常返回响应且http状态码为200
//注意：
//正常返回时一定要保证err_no和err_tips为下面标准返回方式，不然都认为失败，将会重试
{
  "err_no": 0,
  "err_tips": "success"
}
    ​

    异常示例

    //异常响应或http状态码为非200，
//字节服务端会不断重试
{
  "err_no": 1, //非0
  "err_tips": "system error"  //非success
}
    ​

    Q&A

    1.为什么没有收到退款通知

    按以下步骤排查：
      1.发起退款是否已经到终态(成功/失败)，如果处于退款中，不会发退款结果通知
      2.检查是否配置了消息通知地址(配置后需要发布才生效)， 解决方案配置-消息通知
      3.检查消息通知地址对应的服务是否正常，执行下面的命令，如果响应非200，说明服务调不通，请检查自己的服务
    curl -X POST '你的退款通知地址' -H 'Content-Type:application/json'  --data '{
  "version": "2.0",
  "msg": "",
  "type": "refund"
}'
      4.结果通知失败的重试间隔为：10s/10s/30s/1m/2m/3m/4m/5m/6m/7m/8m，一共重试10次，10次后不再重试。
    以上步骤排查过还有问题，请联系 oncall。