基础能力

触达与营销

支付

评价

交易工具

交易系统

通用交易系统

行业交易系统

API 调用

回调设置

预下单

营销算价

支付

核销

分账

退货退款

担保支付（即将下线）

抖店绑定

运营

生活服务

垂直行业

其它

通知退款结果
收藏
我的收藏

退款处理完成后，抖音开平交易系统会给向开发者的服务发起请求，将退款结果通知到开发者服务端。

使用限制

无

接口说明

注意事项

•

退款结果通知地址优先级：退款发起/退款申请回调指定的notify_url>抖音开放平台-小程序应用详情-能力-支付页面设置的回调地址。

•

由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。

•

回调可能存在延时，开发者可以通过主动请求查询退款。

•

回调验签使用的token为在 https://developer.open-douyin.com/microapp/ttf4d2826f6becc24001/pay页面设置中的 token字段。

ttf4d2826f6becc24001为小程序的AppID。

•

在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败进行重试。

•

结果通知失败的重试间隔为：10s/10s/30s/1m/2m/3m/4m/5m/6m/7m/8m，一共重试10次。

•

对于旧订单（担保支付订单）在交易 2.0 发起的退款和分账产生的回调通知，采用的回调签名算法和旧系统（担保支付）保证一致，仅当回调请求中有 version 字段且为 2.0 时，采用签名算法，否则采用的就是旧系统的回调签名算法。

基本信息

基本信息
HTTP URL	•在`https://developer.open-douyin.com/microapp/ttf4d2826f6becc24001/pay`页面设置的支付回调 URL。 `ttf4d2826f6becc24001`为小程序的 `AppID`。 •在退款申请回调响应中指定 notify_url
HTTP Method	POST

请求头

参见通用参数。

请求参数

名称	类型	是否必填	描述	示例值
msg	string	是	订单相关信息的 JSON 字符串	见下文示例
type	string	是	枚举值（退款结果回调为 refund）： •payment：支付成功/支付取消 •refund：退款成功/退款失败） •settle：分账成功/分账失败	refund
version	string	是	固定值："2.0"。回调版本，用于开发者识别回调参数的变更	2.0

msg 字段

名称	类型	是否必填	描述	示例值
app_id	string	是	小程序 id	ttcfdbb96650e33350
status	string	是	退款状态枚举值： •SUCCESS：退款成功 •FAIL：退款失败	SUCCESS
order_id	string	是	抖音开平侧订单号	ot705743551598063048
refund_id	string	是	抖音开平侧退款单号	ot705741681492553429
refund_item_detail	Json Object	是	退款商品单信息
refund_fee_detail	Json Object	否	退款fee
out_refund_no	string	是	开发者自定义的退款单号	5304340298302398023
cp_extra	string	是	退款时开发者传入字段	whatever
refund_total_amount	int64	是	退款金额，单位分	9900
is_all_settled	bool	是	是否为分账后退款	false
event_time	int64	是	退款时间戳，单位为毫秒	1643189272388
message	string	否	结果描述信息，如失败原因
refund_type	int64	否	退款来源类型，枚举值： •1：交易模板发起 •2：开发者发起 •3：商品过期自动发起退款 •4：抖音客服退款 •5：预约失败自动退款	1

refund_item_detail 字段

名称	类型	是否必填	描述	示例值
item_order_quantity	int64	是	用户退款商品单数量	3
item_order_detail	Json Object	是	本次退款的商品单

item_order_detail 字段

名称	类型	是否必填	描述	示例值
item_order_id	string	是	抖音开平侧商品单id	ot705743551598066048
refund_amount	int64	是	该商品单退款金额，单位分	3300

refund_fee_detail字段

名称	类型	是否必填	描述	示例值
fee_type	int	是	18.基建费 19.燃油费 20.税费	18
refund_amount	int64	是	退款金额，必须全额退	100

请求示例

curl --location --request POST 'https://xxxxxxx.net/api/v2/result_callback?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json'
--data-raw='{
  "version": "2.0", //本次固定为2.0, 通过版本信息识别，用不同的结构体去解析上述关键参数
  "msg": "{\"app_id\":\"ttcfdbb96650e33350\",\"status\":\"SUCCESS\",\"order_id\":\"ot7057422956397562142\",\"cp_extra\":\"\",\"message\":\"\",\"event_time\":1643185934447,\"refund_id\":\"ot7057422412346034445\",\"out_refund_no\":\"ext_order_no_1643185898403\",\"refund_total_amount\":1,\"is_all_settled\":false,\"refund_item_detail\":{\"item_order_quantity\":1,\"item_order_detail\":[{\"refund_amount\":1,\"item_order_id\":\"ot7057422956397594910\"}]}}",
  "type": "refund"
}'

msg 字段内容示例

//退款成功回调示例
{
    "app_id": "ttcfdbb96650e33350",
    "status": "SUCCESS",
    "order_id": "ot7057422956397562142",
    "cp_extra": "",
    "message": "",
    "event_time": 1643185934447,
    "refund_id": "ot7057422412346034445",
    "out_refund_no": "ext_order_no_1643185898403",
    "refund_total_amount": 1,
    "is_all_settled": false,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "ot7057422956397594910"
            }]
    },
    "refund_fee_detail": [
        {
            "fee_type": 18,
            "refund_amount": 20
        }
    ]
}


//退款失败回调示例
{
    "app_id": "ttcfdbb96650e33350",
    "status": "FAIL",
    "order_id": "ot7057422956397562142",
    "cp_extra": "xxxxx",
    "message": "XXXXXXXX",
    "event_time": 1643185934447,
    "refund_id": "ot7057422412346034445",
    "out_refund_no": "ext_order_no_1643185898403",
    "refund_total_amount": 1,
    "is_all_settled": true,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "ot7057422956397594910"
            }]
    }
}

响应参数

名称	类型	描述	示例值
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
}

错误码

HTTP状态码	错误码	描述	排查建议
200	0	success	响应成功
200	非0	非success	响应失败

Q&A

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

A: 按以下步骤排查

查询退款是否已经到终态(成功/失败)，如果处于退款中，不会发退款结果通知。

检查是否配置了退款通知地址。

检查退款通知地址对应的服务是否正常，执行下面的命令，如果响应非200，说明服务调不通，请检查自己的服务。

curl -X POST '你的退款通知地址' -H 'Content-Type:application/json'  --data '{
  "version": "2.0",
  "msg": "",
  "type": "refund"
}'

结果通知失败的重试间隔为：10s/10s/30s/1m/2m/3m/4m/5m/6m/7m/8m，一共重试10次，10次后不再重试。

以上步骤排查过还有问题，请联系oncall。

通知退款结果收藏我的收藏