申请退款

退款接口用于对已支付成功的订单发起退款申请。支持全额退款和部分退款。

接口信息

• 接口地址：

  /zro/trade/refund

• 请求方式：POST
• Content-Type：application/json

请求参数

公共参数

参数名	类型	必填	描述
merchantNo	String	是	商户号
sign	String	是	签名

业务参数

参数名	类型	必填	描述
orderNo	String	是	商户订单号
refundMoney	Number	是	退款金额，单位：元，不能超过订单金额
description	String	否	退款描述/退款原因
notifyUrl	String	否	退款结果回调 url

请求示例

{
  "orderNo": "2023083xxxx0325018x8600",
  "retundMoney": "6183.26",
  "description": "用户取消订单",
  "merchantNo": "1004x8xx261",
  "sign": "a92785129faf89f78db05d4440694c58d03e098a162d59e5901cf6c4419067af"
}

响应参数

成功响应

参数名	类型	描述
code	Number	响应码，6000 表示成功
message	String	响应信息
result	Object	退款信息

退款信息（result）

参数名	类型	描述
refundNo	String	嗖付退款单号
orderNo	String	商户订单号
refundStatus	String	退款状态

退款状态说明

状态值	状态描述	说明
PROGRESS	退款处理中	退款申请已提交，正在处理
SUCCESS	退款成功	退款已成功到账
FAILED	退款失败	退款处理失败

响应示例

成功响应

{
  "code": 6000,
  "message": "已提交退款",
  "result": {
    "refundNo": "RF20231119001234567890",
    "orderNo": "ORDER20231119001"
  },
  "request_id": "4e6d479f-8c1b-433b-9d03-c5851b12bf8a",
  "timestamp": "2025-12-25 11:09:18"
}

错误响应

{
  "code": 6015,
  "message": "退款失败"
}

代码示例

Java 示例

RefundRequest request = new RefundRequest();
request.setOrderNo("ORDER20231119001");
request.setRefundMoney(50.00);
request.setDescription("用户申请退款");

RefundResponse response = client.refund(request);
if (response.getCode() == 6000) {
    System.out.println("退款申请成功，退款单号：" + response.getResult().getRefundNo());
}

PHP 示例

$params = [
    'orderNo' => 'ORDER20231119001',
    'refundMoney' => 50.00,
    'description' => '用户申请退款'
];

$response = $client->refund($params);
if ($response['code'] === 6000) {
    echo "退款申请成功，退款单号：" . $response['result']['refundNo'];
}

注意事项

重要提醒

1. 退款金额：不能超过原订单支付金额
2. 退款单号：必须保证在商户端唯一
3. 退款时效：一般情况下，退款会在 1-7 个工作日内到账
4. 部分退款：同一笔订单支持多次部分退款，但累计退款金额不能超过订单金额

相关接口

• 退款查询 - 查询退款状态