退款接口

接口说明

退款接口用于对已支付的订单进行退款操作。支持全额退款和部分退款。

接口信息

• 接口地址: POST /v1/pay/refund
• Content-Type: application/json
• 字符编码: UTF-8
• 签名方式: RSA-SHA256

请求参数

认证信息

请在 HTTP Header 中携带 Authorization 字段,格式详见 接口概览

业务参数

参数名	类型	必填	说明
merchant_no	String	是	商户号
out_trade_no	String	二选一	原商户订单号,服务商自定义
pay_trade_no	String	二选一	原商户单号,由平台生成
out_refund_no	String	是	退款单号,商户系统内唯一
refund_amount	Integer	是	退款金额,单位:分
refund_reason	String	否	退款原因,128字符以内
notify_url	String	否	退款结果通知地址

提示

out_trade_no 和 pay_trade_no 至少提供一个,优先使用 pay_trade_no。

请求示例

POST /v1/pay/refund
Content-Type: application/json
Authorization: RSA service_id=SVC1234567890,timestamp=1704067200,nonce_str=abc123,sign=签名值

{
  "merchant_no": "1234567890",
  "pay_trade_no": "MF20240101120000001",
  "out_refund_no": "REFUND20240101120000",
  "refund_amount": 100,
  "refund_reason": "用户申请退款",
  "notify_url": "https://your-domain.meepay.org/api/refund-notify"
}

响应参数

成功响应

参数名	类型	说明
code	String	响应码,00000 表示成功
msg	String	响应消息
data	Object	业务数据
data.pay_trade_no	String	原商户单号
data.out_trade_no	String	原商户订单号
data.refund_no	String	平台退款号
data.out_refund_no	String	商户退款单号
data.transaction_id	String	交易单号
data.refund_amount	Integer	退款金额,单位:分
data.status	String	退款状态:PROCESSING(处理中)/SUCCESS(成功)/FAILED(失败)
data.pay_method	String	支付方式:wechat/alipay
data.refund_time	String	退款申请时间,格式:yyyyMMddHHmmss

响应示例

微信支付退款

{
  "code": "00000",
  "msg": "success",
  "data": {
    "pay_trade_no": "MF20240101120000001",
    "out_trade_no": "ORDER20240101120000",
    "refund_no": "RF20240101120000001",
    "out_refund_no": "REFUND20240101120000",
    "pay_trade_no": "WX20240101120000001",
    "refund_amount": 100,
    "status": "PROCESSING",
    "pay_method": "wechat",
    "refund_time": "20240101130000"
  }
}

支付宝退款

{
  "code": "00000",
  "msg": "success",
  "data": {
    "pay_trade_no": "MF20240101120000001",
    "out_trade_no": "ORDER20240101120000",
    "refund_no": "RF20240101120000001",
    "out_refund_no": "REFUND20240101120000",
    "pay_trade_no": "ALI20240101120000001",
    "transaction_id": "2024010122001234567890",
    "refund_amount": 100,
    "status": "SUCCESS",
    "pay_method": "alipay",
    "refund_time": "20240101130000"
  }
}

退款状态说明

状态	说明
PROCESSING	退款处理中,等待支付渠道处理
SUCCESS	退款成功,资金已退回
FAILED	退款失败,需重新发起或联系客服

代码示例

Node.js

const crypto = require('crypto');
const https = require('https');

async function refundOrder(tradeNo, refundAmount) {
  const params = {
    service_id: 'SVC1234567890',
    merchant_no: '1234567890',
    trade_no: tradeNo,
    out_refund_no: 'REFUND' + Date.now(),
    refund_amount: refundAmount,
    refund_reason: '用户申请退款',
    notify_url: 'https://your-domain.meepay.org/api/refund-notify',
    timestamp: String(Math.floor(Date.now() / 1000)),
    nonce_str: crypto.randomBytes(16).toString('hex')
  };
  
  params.sign = sign(params, privateKey);
  
  const options = {
    hostname: 'api.meepay.org',
    path: '/v1/pay/refund',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  };
  
  return new Promise((resolve, reject) => {
    const req = https.request(options, (res) => {
      let data = '';
      res.on('data', chunk => { data += chunk; });
      res.on('end', () => resolve(JSON.parse(data)));
    });
    req.on('error', reject);
    req.write(JSON.stringify(params));
    req.end();
  });
}

// 使用示例
const result = await refundOrder('MF20240101120000001', 100);
console.log('退款结果:', result);

注意事项

1. 订单状态: 只能对支付成功的订单进行退款
2. 退款金额:
   • 部分退款: 退款金额 <= 订单金额
   • 全额退款: 退款金额 = 订单金额
   • 累计退款金额不能超过订单金额
3. 退款单号: out_refund_no 在商户系统内必须唯一
4. 退款时效:
   • 微信: 通常1-3个工作日到账
   • 支付宝: 通常即时到账或1-3个工作日
5. 异步通知: 建议提供 notify_url 接收退款结果通知
6. 幂等性: 相同的 out_refund_no 多次请求返回相同结果

错误码

错误码	说明	处理建议
00000	成功	-
10001	参数错误	检查请求参数
10002	签名失败	检查签名算法
40001	订单不存在	检查订单号
40002	订单未支付	只能退款已支付订单
40003	退款金额超限	退款金额超过订单金额
40004	退款单号重复	更换退款单号
40005	退款失败	联系平台处理