申请退款

API文档最后更新: 2026-08-31

7.6 申请退款

  • 请求方式：POST

  • 请求地址：/orders/{clientOrderRef}/refunds

仅当最新订单的 allowedActions 包含 requestRefund 时才能调用。该接口申请退还订单当前全部可退金额，第三方不填写退款金额。

{
  "clientRefundRef": "RF-20260728-0001",
  "reason": "商品无法使用"
}

请求字段：

字段

位置

JSON 类型

必填

含义

clientOrderRef

Path

string

是

要退款的第三方订单号

clientRefundRef

Body

string

是

第三方退款编号，在当前订单内唯一；1 至 64 个字符，只能使用字母、数字、短横线和下划线；网络重试必须继续使用原编号

reason

Body

string

是

申请退款的原因，1 至 255 个字符

返回示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "clientRefundRef": "RF-20260728-0001",
    "refundRef": "RF202607290001",
    "clientOrderRef": "PO-20260728-0001",
    "refundAmount": 100.00,
    "reason": "商品无法使用",
    "createdAt": 1785216100,
    "updatedAt": 1785216100
  },
  "requestId": "req_01K0EXAMPLE"
}

返回字段：

字段

JSON 类型

必填

含义

code

integer

是

固定为 0，表示请求成功

message

string

是

本次请求的处理说明

data

object

是

本次退款申请资料

data.clientRefundRef

string

是

第三方退款编号

data.refundRef

string

是

平台退款编号

data.clientOrderRef

string

是

退款所属的第三方订单号

data.refundAmount

number

是

本次申请退款金额，单位为人民币元，最多保留两位小数

data.reason

string

是

第三方提交的退款原因

data.createdAt

integer

是

退款申请创建时间，10 位 Unix 秒级时间戳

data.updatedAt

integer

是

退款申请最后更新时间，10 位 Unix 秒级时间戳

requestId

string

是

本次请求编号，排查问题时提供给平台

使用规则：

  • clientRefundRef 由第三方生成，在当前订单内不能重复；长度为 1 至 64 个字符，只能使用字母、数字、短横线和下划线。

  • 请求体不接受 refundAmount；平台按订单当时的全部可退金额创建待人工处理申请。

  • 相同 clientRefundRef、订单和原因返回原退款申请，不重复发起；相同引用但内容不同返回 IDEMPOTENCY_CONFLICT。

  • HTTP 2xx 只表示退款申请已经提交，或者返回了之前的同一申请；不会直接改变订单状态或完成退款。

  • 退款申请提交后等待商户处理；接口成功不代表退款已经完成。

  • 实际退款金额、累计退款金额和退款后的订单状态会通过 order.changed 推送。没有收到推送时，可以查询订单详情。

  • 同一退款同时改变订单状态时不会再重复发送 order.changed。

上一篇下一篇