查询退款
收藏我的收藏
收藏开发者可通过此接口查询退款单的详情。适用场景举例：查询是否发起退款，查询退款单状态。
使用限制
无
接口说明
- •支持 refund_id 查询
- •支持 out_refund_no 查询
- •支持 order_id 查询
基本信息
基本信息 | |
HTTP URL | |
HTTP Method | POST |
权限要求 | 无 |
请求头
名称 | 类型 | 是否必填 | 描述 |
Content-Type | string | 是 | 固定值 "application/json" |
Byte-Authorization | string | 是 |
请求参数
注意：
- 1.refund_id , out_refund_no , order_id 三选一，不能都不选。
- 2.order_id维度的不兼容老退款单查询，只支持查询交易系统的退款。查询返回的结果数限制50条
名称 | 类型 | 是否必填 | 描述 | 示例值 |
refund_id | string | 否 | 抖音开平内部交易退款单号，长度 <= 64byte | ot1231231 |
out_refund_no | string | 否 | 开发者系统生成的退款单号，长度 <= 64byte | 12313 |
order_id | string | 否 | 抖音开平内部交易订单号， 长度 <= 64byte | ot7231231 |
请求示例
curl --location --request POST 'https://developer.toutiao.com/api/apps/trade/v2/query_refund' \ --header 'Content-Type: application/json' \ --header 'Byte-Authorization: SHA256-RSA2048 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="' --data-raw='{ "refund_id": "ot1231231", //当有refund_id时，优先使用refund_id查询 "out_refund_no": "12313" }'
响应参数
名称 | 类型 | 是否必填 | 描述 | 示例 |
err_no | int64 | 是 | 状态码 0 表示业务处理成功，具体错误码参见后文错误码章节 | 0 |
err_tips | string | 是 | 错误提示信息 | success |
data | object | 否 | 返回数据信息 | success |
data 信息
名称 | 类型 | 是否必填 | 描述 | 示例 |
refund_list | Array<object> | 是 | 退款查询结果列表，最多返回50条 (建议开发者用这个字段) | |
refund_list 说明
名称 | 类型 | 是否必填 | 描述 | 示例 |
refund_id | string | 是 | 系统退款单号，开放平台生成的退款单号 | ot13213 |
out_refund_no | string | 否 | 开发者系统生成的退款单号，与抖音开平退款单号 refund_id 唯一关联 | 2313 |
refund_total_amount | int64 | 是 | 退款金额，单位[分] | 100 |
refund_status | string | 是 | 退款状态 退款中- PROCESSING 已退款- SUCCESS 退款失败- FAIL | PROCESSING |
refund_at | int64 | 否 | 退款时间，13 位毫秒时间戳，只有已退款才有退款时间 | 1643009622000 |
message | string | 否 | 退款结果信息，非商家拒绝退款导致的退款失败，可以通过该字段了解退款失败原因 | 退款失败 |
order_id | string | 是 | 系统订单信息，开放平台生成的订单号 | ot123123 |
item_order_detail | Array<object> | 否 | 商品单信息 (交易系统订单退款才有的信息) | |
merchant_audit_detail | object | 否 | 退款审核信息 (交易系统订单退款才有的信息) | |
create_at | int64 | 是 | 退款创建时间，13 位毫秒时间戳 | 1643009622000 |
refund_source | int64 | 否 | 退款来源，仅交易2.0退款有来源，老的担保交易/1.0订单可能没有记录来源 1: 用户发起退款 2: 开放者发起退款 3: 自动退款 4: 抖音客服退款 5: 预约失败自动发起退款 6: 开发者拒绝接单退款 7: 后约单触发先买单退款 | 1 |
item_order_detail 说明
名称 | 类型 | 是否必填 | 描述 | 示例值 |
item_order_id | string | 是 | 抖音开平侧的商品单号 | ot123123 |
refund_amount | int64 | 是 | 该商品单退款金额，单位[分] | 50 |
merchant_audit_detail 说明
名称 | 类型 | 是否必填 | 描述 | 示例 |
refund_audit_deadline | int64 | 是 | 退款审核的最后期限，过期无需审核，自动退款，13 位 unix 时间戳，精度：毫秒 | 151231321231 |
audit_status | string | 是 | 退款审核状态：
| AGREE |
deny_message | string | 否 | 不同意退款信息，长度 <= 512 byte | 不同意退款 |
响应示例
正常示例
- •由于旧协议没有兼容退款结果列表，所以新增了refund_list字段，建议开发者使用refund_list字段
{ "data": { "refund_list": [ { "refund_at": 1672994501000, "create_at": 1672994428929, "refund_source": 1, "refund_total_amount": 1992, "refund_status": "SUCCESS", "out_refund_no": "ext_refund_no_718536707992153502030519534", "message": "", "item_order_detail": [ { "item_order_id": "800000000101757849613437984", "refund_amount": 996 }, { "item_order_id": "800000000101757824013547984", "refund_amount": 996 } ], "merchant_audit_detail": { "audit_status": "AGREE", "deny_message": "", "need_refund_audit": 1, "refund_audit_deadline": 1673253628929 }, "order_id": "8000000001017577984", "refund_id": "718536707992153502030519534" } ] }, "resp_extra": { "logid": "02168173448144300000000000000000000ffff0a99604dfab9fd" }, "err_no": 0, "err_tips": "success" }
异常示例
{ "err_no": 13000, "err_tips": "系统错误" }
错误码
错误码 | 错误提示 | 建议解决方案 |
20000 | 订单不存在 | 按以下步骤进行排查：
以上步骤都排查过，仍然无法处理时请提oncall |
1.为什么开发者未发起退款，但是查询到订单在退款中？
A：除开发者发起外，还存在用户在退款组件发起、系统自动退款、抖音客服发起等场景，请通过 查询退款接口查询订单的退款记录，并检查 refund_source 字段，可以获得具体的退款来源。
2.为什么订单会存在抖音客服发起的退款
