退款发起

建议超时 15000ms。幂等键：商户号 + out_refund_no。对成功扣款原路退（全额/部分）。原单定位：original_trade_no 与 original_out_trade_no 至少填一个；两者都填时以 original_trade_no 为准。终态完成时间字段为 order_finish_time。

同步应答与是否落单（须区分）：

场景	是否落退款单	应答形态	说明
占用校验超额（可退金额不足）等业务拒单	否	失败信封（`code`/`message`，无 `refund_status`）	如 `TRADE_ERROR`，文案含「可退金额不足」
校验通过已落单，渠道同步明确失败	是	成功业务体，`refund_status=FAIL`	FAIL 不占可退额度；与校验超额不是同一口径
校验通过已落单，受理中/成功	是	成功业务体，`refund_status` 为 INIT / PROCESSING / SUCCESS	INIT/PROCESSING/SUCCESS 占用可退额度

接口说明

请求方式：【POST】/v1/wallet/refund/apply

请求域名：【主域名】https://api.baofu.com

请求参数

Header 参数

参数名	类型	必填	描述
Authorization	string	true	请参考【开发指引-整体说明】生成认证信息
Accept	string	true	请设置为 `application/json`
Content-Type	string	true	请设置为 `application/json`

Body 参数

参数名	类型	必填	描述
out_refund_no	string	true	商户退款单号；≤64
original_trade_no	string	false	原平台扣款单号；≤64；与 original_out_trade_no 至少填一个；两者都填时以本字段为准
original_out_trade_no	string	false	原商户扣款订单号；≤64；与 original_trade_no 至少填一个
refund_amount	integer	true	本次退款金额；>0；单位分
notify_url	string	false	退款结果异步通知；≤256；未上送则不通知
reason	string	false	退款原因；≤80

请求示例

{
  "out_refund_no": "RF202607300001",
  "original_trade_no": "4101010120250525120000000001",
  "refund_amount": 1,
  "notify_url": "https://merchant.example.com/notify/refund",
  "reason": "用户取消"
}

应答参数

200 OK

参数名	类型	必填	描述
refund_no	string	false	平台退款单号
out_refund_no	string	false	商户退款单号
original_trade_no	string	false	原平台扣款单号
original_out_trade_no	string	false	原商户扣款订单号
refund_amount	integer	false	退款金额（分）
refund_status	string	false	INIT / PROCESSING / SUCCESS / FAIL
create_time	string	false	ISO 8601
order_finish_time	string	false	订单完成时间；成功或失败时有值

应答示例

200 OK

{
  "refund_no": "5101010120260730120000000001",
  "out_refund_no": "RF202607300001",
  "original_trade_no": "4101010120250525120000000001",
  "original_out_trade_no": "DED202505250001",
  "refund_amount": 1,
  "refund_status": "PROCESSING",
  "create_time": "2026-07-30T12:00:00+08:00"
}

错误码

公共错误码

状态码	错误码	描述	解决方案
401	SIGN_ERROR	验证不通过	请参阅【开发指引-整体说明】排查签名
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
非 200	ORDER_DUPLICATED	out_refund_no 已存在	查退款
非 200	TRADE_ERROR	可退不足、原单非成功等	核查原支付与金额
非 200	INVALID_PARAMETER	参数错误	修正后重试

应答示例

失败

{
  "code": "ORDER_DUPLICATED",
  "message": "交易失败"
}

应答示例

失败

{
  "code": "TRADE_ERROR",
  "message": "交易失败"
}

应答示例

失败

{
  "code": "INVALID_PARAMETER",
  "message": "交易失败"
}