- 小程序 OpenAPI SDK 总览
- OpenAPI 简介
- 用户登录态签名
- 签名算法
- 联合授权
- 接口调用凭证
- 登录
- 小程序码与小程序链接
- Web 化接入
- 私信和群聊
- 解决方案
- 线索组件
- 隐私协议
- 视频能力
- 搜索能力
- 任务能力
- 电商
- 生活服务
- 短剧行业
- 用户信息
- 分享
- 客服
- 交易工具
- 小程序券
- 交易系统
- 素材库
- 内容安全
- 泛知识
- 担保支付
- 评价
- 其它
- 订阅消息
- 小程序推广计划
- 挂载
- 分发
- 数据分析
- 服务类目
- 直播间能力
- 抖音开放能力
- 能力申请
- 页面结构自定义
- 普通二维码绑定
- 抖音号绑定
- 流量主
- 抖店绑定
通知退款结果收藏我的收藏
收藏
我的收藏退款处理完成后,抖音开平交易系统会给向开发者的服务发起请求,将退款结果通知到开发者服务端。
使用限制
无。
注意事项
- •由于网络波动等原因,可能会产生重复的通知消息,接入方需要做好幂等,正确处理。
- •回调可能存在延时,开发者可以通过主动请求查询退款
- •回调验签使用的 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 。
| |||
HTTP Method | POST |
请求头
请求参数
名称 | 类型 | 是否必填 | 描述 | 示例值 |
msg | string | 是 | 订单相关信息的 JSON 字符串 | 见下文示例 |
type | string | 是 | 枚举值(退款结果回调为 refund):
| refund |
version | string | 是 | 固定值:"2.0"。 回调版本,用于开发者识别回调参数的变更 | 2.0 |
msg 字段
名称 | 类型 | 是否必填 | 描述 | 示例值 |
app_id | string | 是 | 小程序 id | ttcfdbb96650e33350 |
status | string | 是 | 退款状态枚举值:
| 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 |
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 |
请求示例
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 字段内容示例
text复制//退款成功回调示例
{
"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 |
响应示例
正常示例
text复制
//正常返回响应且http状态码为200
//注意:
//正常返回时一定要保证err_no和err_tips为下面标准返回方式,不然都认为失败,将会重试
{
"err_no": 0,
"err_tips": "success"
}
异常示例
text复制
//异常响应或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
点击纠错