H Honor
ZH
DiDi finanzas

文档中心

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

2.8 Refund

2.8 Refund 退款

  • Path： /external/refund/v1

  • Method: POST

  • API 说明：该 API 供合作方对交易发起退款，可用于用户主动发起或系统主动发起的场景。

Request Message

Request Header

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

Request Body

字段名称 类型 字段说明 展示 (必填​**/选填/条件性)** 备注
partnerOrderId String 商户侧支付单据ID 必填
partnerRefundId String 商户侧退款单据ID 必填 幂等键
refundAmount Long 退款金额 必填 实际退款金额
金额单位为分。例如，若金额为99.99比索，此处的值应为9999。
退款金额 = 退款单价 * 退款数量 之和
refundType String 退款类型 必填 枚举：
PART_REFUND-部分退款
ALL_REFUND-全额退款
currency String 币种 必填 ISO 4217 标准
墨西哥比索
refundTime String 退款时间 必填 格式：yyyy-MM-dd'T'HH:mm:ss.SSSXXX
例如：'2025-12-08T01:11:33.000+08:00'。时区偏移为必填项。

请求示例

{
    "partnerOrderId": "1e1e51a8-8d38-11ef-b32d-ca3c6358d263",
    "partnerRefundId": "f0136e12-8d3f-11ef-b32d-ca3c6358d263",
    "refundAmount": 5000,
    "refundType":"ALL_REFUND",
    "currency": "MXN",
    "refundTime": "2024-10-11T17:10:00.000+08:00"
}

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侧创建支付订单接口
refundId String 退款ID 选填 滴滴先享后付-侧生成
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-xxxx-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
}
复制成功