查询退款

更新时间 2024-08-19 09:14:50

我的收藏

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

使用限制

无

接口说明

•

支持 refund_id 查询

•

支持 out_refund_no 查询

•

支持 order_id 查询

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/apps/trade/v2/refund/query_refund
HTTP Method	POST
Scope	industry_open.trade.refund
权限要求	不需要用户授权

请求头

参考通用参数-开发者请求公共参数

请求参数

注意：

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

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

名称	类型	是否必填	描述	示例值
refund_id	`string`	否	抖音开平内部交易退款单号，长度 <= 64byte	ot1231231
out_refund_no	`string`	否	开发者系统生成的退款单号，长度 <= 64byte	12313
order_id	`string`	否	抖音开平内部交易订单号，长度 <= 64byte	ot7123231

请求示例

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/refund/query_refund' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "refund_id": "ot1231231", //当有refund_id时，优先使用refund_id查询
        "out_refund_no": "12313"
}'

响应参数

名称	类型	是否必填	描述	示例
data	`object`	否	返回数据信息	success
extra	`object`	是	额外信息，参考通用参数中的说明

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`	是	退款审核状态： •INIT：初始化 •TOAUDIT：待审核 •AGREE：同意 •DENY：拒绝 •OVERTIME：超时未审核自动同意	AGREE
deny_message	`string`	否	不同意退款信息，长度 <= 512 byte	不同意退款

响应示例

正常示例

•

由于旧协议没有兼容退款结果列表，所以新增了refund_list字段，建议开发者使用refund_list字段

json复制
{
  "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"
      }
    ],
    "error_code": 0,
    "description": ""
  },
  "extra": {
    "error_code": 0,
    "description": "",
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "02168173575240700000000000000000000ffff0a706f38ab32d2",
    "now": 1681735753
  }
}

异常示例

json复制
{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

详情参见错误码/返回码。

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