查询退款

title: 查询退款

order: 3

keywords:

intro:

type: other

validate: false

publicity: true

showUpdateTime: true

time: 1684292204000

开发者可通过此接口查询退款单的详情。适用场景举例：查询是否发起退款，查询退款单状态。

接口说明

支持 refund_id 查询

支持 out_refund_no 查询

支持 order_id 查询

请求参数

注意：

refund_id , out_refund_no , order_id 三选一，不能都不选。

order_id维度的不兼容老退款单查询，只支持查询交易系统的退款。查询返回的结果数限制50条

错误码

错误码	错误提示	建议解决方案
20000	订单不存在	按以下步骤进行排查：若刚刚发起退款，系统有延迟，建议等几秒钟再重试请仔细核对参数，out_refund_no、refund_id、order_id与app_id是否匹配如果是以refund_id、order_id查询，说明没有对应的退款单。如果是以out_refund_no查询，很可能是out_refund_no不存在。建议改用order_id查询退款，确认是否存在退款单。如果不存在退款单，说明没有成功发起退款。如果存在退款单且out_refund_no为空，说明开发者未响应退款申请回调。建议检查退款申请回调接口。具体请参考退款申请回调文档末尾的退款申请回调接口排查模块以上步骤都排查过，仍然无法处理时请提oncall

curl --location --request POST 'http://dev-cn.your-api-server.com/api/apps/trade/v2/refund/query_refund' \ --header 'access-token: clt.xxx' \ --header 'Content-Type: application/json' \ --data-raw '{ "refund_id": "ot1231231", //当有refund_id时，优先使用refund_id查询 "out_refund_no": "12313" }'

{ "data": { "refund_list": [ { "merchant_audit_detail": { "audit_status": "AGREE", "need_refund_audit": 1, "refund_audit_deadline": 1673253628929 }, "create_at": 1671994501000, "refund_at": 1672994501000, "refund_status": "SUCCESS", "refund_total_amount": 1992, "item_order_detail": [ { "item_order_id": "800000000101757849613437984", "refund_amount": 996 }, { "refund_amount": 996, "item_order_id": "800000000101757824013547984" } ], "message": "", "order_id": "8000000001017577984", "out_refund_no": "ext_refund_no_718536707992153502030519534", "refund_id": "718536707992153502030519534" } ], "order_id": "8000000001017577984", "refund_id": "718536707992153502030519534", "refund_status": "SUCCESS", "refund_total_amount": 1992, "merchant_audit_detail": { "audit_status": "AGREE", "need_refund_audit": 1, "refund_audit_deadline": 1673253628929 }, "message": "", "create_at": 1671994501000, "refund_at": 1672994501000, "item_order_detail": [ { "item_order_id": "800000000101757849613437984", "refund_amount": 996 }, { "item_order_id": "800000000101757824013547984", "refund_amount": 996 } ], "out_refund_no": "ext_refund_no_718536707992153502030519534", "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "success", "logid": "02168173575240700000000000000000000ffff0a706f38ab32d2", "now": 1681735753 } }

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/json

access-token

string

必需

示例值:

clt.xxx

Body 参数application/json

refund_id

string

可选

当有refund_id时，优先使用refund_id查询

out_refund_no

string

可选

开发者系统生成的退款单号，长度 <= 64byte

示例

返回响应

🟢200成功

application/json

Body

data

object

可选

refund_list

array [object {10}]

必需

退款查询结果列表，最多返回50条 (建议开发者用这个字段)

order_id

string

必需

系统订单信息，开放平台生成的订单号

refund_id

string

必需

系统退款单号，开放平台生成的退款单号

refund_status

string

必需

退款状态退款中- PROCESSING 已退款- SUCCESS 退款失败- FAIL

refund_total_amount

integer

必需

退款金额，单位[分]

merchant_audit_detail

object

可选

退款审核信息 (交易系统订单退款才有的信息)

message

string

可选

退款结果信息，非商家拒绝退款导致的退款失败，可以通过该字段了解退款失败原因

create_at

integer

必需

refund_at

integer

可选

退款时间，13 位毫秒时间戳，只有已退款才有退款时间

item_order_detail

array [object {2}]

可选

商品单信息 (交易系统订单退款才有的信息)

out_refund_no

string

可选

开发者系统生成的退款单号，与抖音开平退款单号 refund_id 唯一关联

error_code

integer

必需

description

string

必需

extra

object

必需

额外信息，参考通用参数中的说明

error_code

integer

必需

description

string

必需

sub_error_code

integer

必需

sub_description

string

必需

logid

string

必需

now

integer

必需

🟠400请求有误

接口说明#

请求参数#

错误码#

请求参数

返回响应

接口说明

请求参数

错误码