H Honor
ZH
DiDi finanzas

文档中心

提供接入指南、接口文档、测试指引等全流程接入所需信息

2.9 Refund Query

2.9 Refund Query 退款信息查询

  • Path：/external/refund/query/v1

  • Method: POST

  • 接口说明：这是供合作方查询退款信息，尤其是退款状态的应用程序编程接口。

  • 使用说明：有时， 退款信息查询 应用程序编程接口可能会因某些不可预知的原因返回错误。合作方不得将该查询接口的错误视为 退款结果。合作方应将查询接口返回的具体结果作为 退款结果。

  • 补充说明：尽管滴滴会向合作方发送 Webhook ，但查询 API 是强制要求使用的。这是一项兜底策略，供合作方在 Webhook 投递失败时获取 退款状态 。

Request Message

Request Header

字段名称 字段说明 参数值 展示 (必填​**/选填/条件性)** 备注
Content-Type 内容类型 application/json 必填
Authorization 这是合作伙伴的身份认证值。 Bearer {ACCESS-TOKEN} 必填 详情请参见 请参阅"第2部分 DiDi BNPL合作伙伴配置和环境设置"。
合作伙伴可通过 ACCESS-TOKEN 值来自对令牌API的调用。
当访问令牌过期时，再次调用令牌API以获取新的访问令牌。
X-Paylater-Request-Id 通用唯一标识符 uuid.
Example: 550e8400-e29b-41d4-a716-446655440000		 必填 必填的 UUID v4 字符串。滴滴将拒绝格式无效的请求。

Request Body

字段名称 类型 字段说明 展示 (必填​**/选填/条件性)** 备注
partnerRefundId String 商户侧退款单ID 必填

Request Example

{
    "partnerRefundId": "f0136e12-8d3f-11ef-b32d-ca3c6358d263"
}

Response Message

Response Header

字段名称 字段描述 参数值 展示 (必填​**/选填/条件性)** 备注
Content-Type 内容类型 application/json 必填

Response Body

字段名称 类型 字段说明 展示 (必填​**/选填/条件性)** 备注
code String 返回码 必填 枚举值：
SUCCESS
FAILED
RATE_LIMIT
INVALID_TOKEN
message String 响应码说明 必填
data Object 退款订单信息 选填
partnerRefundId String 商户侧退款单ID 必填
partnerOrderId String 商户侧支付单据ID 必填
orderId String 订单ID 选填 在DiDi Paga Después侧创建支付订单API
refundId String 退款ID 选填 由DiDi Paga Después侧生成
partnerUid String 商户侧用户ID 选填
refundAmount Long 退款金额 必填 实际退款金额
金额单位为分。例如，若为99.99比索，此处的值应为9999。
refundType String 退款类型 选填 枚举：
PART_REFUND-部分退款
ALL_REFUND-全额退款
currency String 货币 选填 ISO 4217 标准
墨西哥比索
refundStatus String 退款状态 选填 枚举值：
INIT: 初始化
PENDING: 处理中
SUCCESS: 退款成功
FAILED: 退款失败
rejectCode String 拒绝码 选填 枚举值：
AmountNotAllowed – 退款金额不符合要求条件
AlreadyRefund: 退款请求重复
PaylaterRuleRejected: 被先享后付规则驳回
UnpaidOrder: 订单尚未支付
NotExistOrder: 订单不存在
rejectMsg String 拒绝原因 选填
refundTime String 退款时间 选填 pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
例如：'2025-12-08T01:11:33.000+08:00'。必须指定时区偏移量。
createTime String 退款创建时间 选填 pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
例如：'2025-12-08T01:11:33.000+08:00'。时区偏移为必填项。
updateTime String 退款更新时间 选填 pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
例如，'2025-12-08T01:11:33.000+08:00'。时区偏移为必填项。
test Boolean 测试表单标签 选填
error Object 错误 选填
errorCode String 错误码 选填
errorMessage String 错误码描述 选填

响应示例

{
    "code": "SUCCESS",
    "message": "SUCCESS",
    "data": {
        "partnerOrderId": "1e1e51a8-8d38-11ef-b32d-ca3c6358d263",
        "partnerRefundId": "f0136e12-8d3f-11ef-b32d-ca3c6358d263",
        "orderId": "189d141e-8d38-11ef-b32d-ca3c6358d263",
        "refundId": "1658fd86-8d41-11ef-b32d-ca3c6358d263",
        "partnerUid": "01213121131",
        "refundAmount": 5000,
        "refundType":"ALL_REFUND",
        "currency": "MXN",
        "refundStatus": "INIT",
        "rejectCode": null,
        "rejectMsg": null,
        "refundTime": "2024-10-14T16:30:39.000+08:00",
        "createTime": "2024-10-14T16:30:39.000+08:00",
        "updateTime": "2024-10-14T16:30:39.000+08:00",
        "test": true
    },
    "error": null
}
复制成功