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

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

使用限制

无。

注意事项

•

退款结果通知地址优先级：退款发起/退款申请回调指定的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	是	退款商品单信息
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

请求示例

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"
            }]
    }
}


//退款失败回调示例
{
    "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
}

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

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

​使用限制​

​注意事项​

​基本信息​

​请求头​

​请求参数​

​msg 字段​

​refund_item_detail 字段​

​item_order_detail 字段​

​请求示例​

​msg 字段内容示例​

​响应参数​

​响应示例​

​正常示例​

​异常示例​

​Q&A​

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