抖音开放平台Logo
控制台

退款结果通知

更新时间 2024-07-24 02:58:49
收藏
我的收藏
退款处理完成后，抖音开平交易系统会给向开发者的服务发起请求，将退款结果通知到开发者服务端。​

​使用限制​

无。​

​注意事项​

    •​由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。​
    •​在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 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）：​
    •​payment：支付成功/支付取消​
    •​refund：退款成功/退款失败）​
    •​settle：分账成功/分账失败​
refund​
​
version​
string​
是​
固定值："2.0"。​
回调版本，用于开发者识别回调参数的变更​
2.0​

​msg 字段​

名称​
类型​
是否必填​
描述​
示例值​
app_id​
string​
是​
小程序 id​
ttcfdbb96650e33350​
status​
​
string​
​
是​
​
退款状态枚举值：​
    •​SUCCESS：退款成功​
    •​FAIL：退款失败​
SUCCESS​
​
order_id​
string​
是​
抖音开平侧订单号​
ot7057435515980663048​
​
refund_id​
string​
是​
抖音开平侧退款单号​
ot7057416814925531429​
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​
ot7057435515980663048​
refund_amount​
int64​
是​
该商品单退款金额，单位分​
3300​

​请求示例​

text
复制
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 字段内容示例​

JSON
复制
//退款成功回调示例
{
"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​

​响应示例​

​正常示例​

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

​异常示例​

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

​Q&A​

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

​A: 按以下步骤排查​
    1.​发起退款是否已经到终态(成功/失败)，如果处于退款中，不会发退款结果通知​
    2.​检查是否配置了消息通知地址(配置后需要发布才生效)， 解决方案配置-消息通知​
    3.​检查消息通知地址对应的服务是否正常，执行下面的命令，如果响应非200，说明服务调不通，请检查自己的服务​
Plain Text
复制
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​