MPay 开发文档

欢迎使用 MPay 支付平台，本文档将帮助您快速接入我们的支付服务。

快速接入

1. 获取密钥

登录商户平台，在「开发对接」-「API密钥」中获取您的 mch_no（商户号）和 api_key（API密钥）。

2. 接口地址

签名认证

所有 API 请求都需要进行签名认证，签名算法如下：

1. 将请求参数按照参数名 ASCII 码从小到大排序
2. 使用 URL 键值对的格式拼接成字符串
3. 在字符串末尾拼接 &key=您的API密钥
4. 对拼接后的字符串进行 MD5 运算，并转换为大写

签名示例

// Node.js 示例
const crypto = require('crypto');

function sign(params, apiKey) {
  const sortedKeys = Object.keys(params).sort();
  const stringA = sortedKeys
    .map(key => `${key}=${params[key]}`)
    .join('&');
  const stringSignTemp = `${stringA}&key=${apiKey}`;
  return crypto.createHash('md5')
    .update(stringSignTemp)
    .digest('hex')
    .toUpperCase();
}

创建订单

POST/pay/create

创建支付订单，获取支付参数。

请求参数

请求示例

{
  "merchant_id": "M1234567890",
  "out_trade_no": "ORDER202401010001",
  "amount": 9900,
  "channel": "wechat",
  "subject": "测试商品",
  "notify_url": "https://your-domain.com/notify",
  "timestamp": "1704067200",
  "sign": "A1B2C3D4E5F6..."
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "order_id": "P202401010001",
    "pay_url": "https://pay.mpay.com/...",
    "qr_code": "weixin://wxpay/..."
  }
}

查询订单

POST/pay/query

查询订单支付状态。建议在以下场景调用：

• 用户支付后跳转回商户页面时
• 未收到回调通知时主动查询
• 对账时核实订单状态

请求参数

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "order_no": "P202401010001",
    "out_trade_no": "ORDER202401010001",
    "amount": 9900,
    "pay_type": "wechat_native",
    "status": 1,
    "status_desc": "已支付",
    "transaction_id": "4200001234202401010001",
    "pay_time": "2024-01-01 12:00:00",
    "create_time": "2024-01-01 11:55:00"
  }
}

订单状态说明

关闭订单

POST/pay/close

关闭未支付的订单。

申请退款

POST/pay/refund

对已支付的订单发起退款申请。

支付回调

支付成功后，系统会向您配置的 notify_url 发送 POST 请求通知支付结果。

回调参数

回调示例

{
  "order_no": "P202401010001",
  "out_trade_no": "ORDER202401010001",
  "amount": 9900,
  "status": 1,
  "transaction_id": "4200001234202401010001",
  "pay_time": "2024-01-01 12:00:00",
  "timestamp": 1704067200,
  "sign": "A1B2C3D4E5F6..."
}

回调处理示例

// Node.js Express 示例
app.post('/notify', (req, res) => {
  const data = req.body;
  
  // 1. 验证签名
  const sign = data.sign;
  delete data.sign;
  const mySign = generateSign(data, API_KEY);
  if (sign !== mySign) {
    return res.send('fail');
  }
  
  // 2. 检查订单状态
  if (data.status !== 1) {
    return res.send('fail');
  }
  
  // 3. 检查金额是否匹配
  const order = await Order.findOne({ orderNo: data.out_trade_no });
  if (order.amount !== data.amount) {
    return res.send('fail');
  }
  
  // 4. 更新订单状态（注意幂等性）
  if (order.status === 'paid') {
    return res.send('success'); // 已处理过
  }
  
  await Order.updateOne(
    { orderNo: data.out_trade_no },
    { status: 'paid', paidAt: data.pay_time }
  );
  
  // 5. 返回成功
  res.send('success');
});

退款回调

退款处理完成后，系统会向您配置的回调地址发送退款结果通知，参数格式与支付回调类似。

退款回调参数