📖 API文档
📌 重要：所有API请求都需要包含正确的通讯密钥进行验证。
🔗 基础信息
| 项目 |
说明 |
| API基础地址 |
http://您的域名/ |
| 请求方式 |
POST / GET |
| 返回格式 |
JSON |
| 字符编码 |
UTF-8 |
📝 创建订单 API
POST
/createOrder
创建新的支付订单
请求参数
| 参数名 |
类型 |
必填 |
说明 |
示例值 |
| payId |
string |
是 |
商户订单号（唯一） |
ORDER_20241201_001 |
| type |
int |
是 |
支付类型：1=微信，2=支付宝 |
1 |
| price |
float |
是 |
支付金额（元） |
10.00 |
| param |
string |
否 |
自定义参数 |
user_id=123 |
| notifyUrl |
string |
否 |
异步通知地址 |
http://your-site.com/notify |
| returnUrl |
string |
否 |
同步跳转地址 |
http://your-site.com/return |
| isHtml |
int |
否 |
是否返回HTML：1=是，0=否 |
0 |
返回示例
{
"code": 1,
"msg": "成功",
"data": {
"payId": "ORDER_20241201_001",
"orderId": "20241201123456789",
"payType": 1,
"price": 10.00,
"reallyPrice": 10.01,
"payUrl": "wxp://f2f0...",
"isAuto": 1,
"state": 0,
"timeOut": 300,
"date": 1701234567
}
}
🔍 查询订单 API
请求参数
| 参数名 |
类型 |
必填 |
说明 |
示例值 |
| payId |
string |
是 |
商户订单号 |
ORDER_20241201_001 |
返回示例
{
"code": 1,
"msg": "成功",
"data": {
"payId": "ORDER_20241201_001",
"orderId": "20241201123456789",
"price": 10.00,
"reallyPrice": 10.01,
"state": 1,
"payDate": 1701234567
}
}
❌ 关闭订单 API
POST
/closeOrder
关闭未支付的订单
请求参数
| 参数名 |
类型 |
必填 |
说明 |
示例值 |
| payId |
string |
是 |
商户订单号 |
ORDER_20241201_001 |
📊 系统状态 API
返回示例
{
"code": 1,
"msg": "成功",
"data": {
"monitor_state": 1,
"last_heart": 1701234567,
"today_orders": 15,
"today_amount": 150.00,
"pending_orders": 2
}
}
🔔 异步通知
当订单支付成功时，系统会向您设置的 notifyUrl 发送POST请求：
{
"payId": "ORDER_20241201_001",
"orderId": "20241201123456789",
"price": 10.00,
"reallyPrice": 10.01,
"param": "user_id=123",
"state": 1,
"payDate": 1701234567
}
⚠️ 注意：请在接收到通知后返回字符串 "success" 表示处理成功，否则系统会重复发送通知。
🔗 系统对接
💻 PHP对接示例
<?php
// V免签API对接示例
class VMQPayment {
private $apiUrl = 'http://your-domain.com/';
private $key = 'your-communication-key';
/**
* 创建订单
*/
public function createOrder($payId, $type, $price, $notifyUrl = '', $returnUrl = '') {
$data = [
'payId' => $payId,
'type' => $type,
'price' => $price,
'notifyUrl' => $notifyUrl,
'returnUrl' => $returnUrl,
'key' => $this->key
];
return $this->request('createOrder', $data);
}
/**
* 查询订单
*/
public function getOrder($payId) {
$data = [
'payId' => $payId,
'key' => $this->key
];
return $this->request('getOrder', $data);
}
/**
* 发送请求
*/
private function request($action, $data) {
$url = $this->apiUrl . $action;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
}
// 使用示例
$vmq = new VMQPayment();
// 创建微信支付订单
$result = $vmq->createOrder('ORDER_001', 1, 10.00, 'http://your-site.com/notify');
if ($result['code'] == 1) {
echo '订单创建成功，支付链接：' . $result['data']['payUrl'];
} else {
echo '订单创建失败：' . $result['msg'];
}
?>
🌐 JavaScript对接示例
// V免签JavaScript对接示例
class VMQPayment {
constructor(apiUrl, key) {
this.apiUrl = apiUrl;
this.key = key;
}
// 创建订单
async createOrder(payId, type, price, notifyUrl = '', returnUrl = '') {
const data = {
payId: payId,
type: type,
price: price,
notifyUrl: notifyUrl,
returnUrl: returnUrl,
key: this.key
};
return await this.request('createOrder', data);
}
// 查询订单
async getOrder(payId) {
const data = {
payId: payId,
key: this.key
};
return await this.request('getOrder', data);
}
// 发送请求
async request(action, data) {
const url = this.apiUrl + action;
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams(data)
});
return await response.json();
} catch (error) {
console.error('API请求失败:', error);
return { code: -1, msg: '网络错误' };
}
}
}
// 使用示例
const vmq = new VMQPayment('http://your-domain.com/', 'your-key');
// 创建支付宝订单
vmq.createOrder('ORDER_002', 2, 20.00, 'http://your-site.com/notify')
.then(result => {
if (result.code === 1) {
console.log('订单创建成功:', result.data);
// 跳转到支付页面或显示二维码
} else {
console.error('订单创建失败:', result.msg);
}
});
🔄 订单状态轮询
// 订单状态轮询示例
function pollOrderStatus(payId, maxAttempts = 60, interval = 5000) {
let attempts = 0;
const poll = () => {
attempts++;
vmq.getOrder(payId).then(result => {
if (result.code === 1) {
const order = result.data;
if (order.state === 1) {
// 支付成功
console.log('支付成功！');
onPaymentSuccess(order);
} else if (order.state === 2) {
// 订单过期
console.log('订单已过期');
onPaymentExpired(order);
} else if (attempts < maxAttempts) {
// 继续轮询
setTimeout(poll, interval);
} else {
// 轮询超时
console.log('轮询超时');
onPaymentTimeout(order);
}
} else {
console.error('查询失败:', result.msg);
}
});
};
poll();
}
function onPaymentSuccess(order) {
// 支付成功处理逻辑
alert('支付成功！订单号：' + order.payId);
window.location.href = '/success.html';
}
function onPaymentExpired(order) {
// 订单过期处理逻辑
alert('订单已过期，请重新下单');
window.location.href = '/expired.html';
}
function onPaymentTimeout(order) {
// 轮询超时处理逻辑
alert('支付超时，请刷新页面查看状态');
}
❓ 常见问题
💡 功能相关
Q: 系统支持哪些支付方式？
A: 目前支持微信支付和支付宝支付两种方式。微信支持扫码支付和赞赏码两种模式。
Q: 为什么需要监控端APP？
A: 监控端APP负责监听微信、支付宝的收款通知，将支付信息实时同步到服务端。这是实现免签约收款的核心机制。
Q: 支付金额为什么会有小数点？
A: 系统会在原金额基础上增加1-99分的随机金额，用于区分不同订单，避免金额重复导致的匹配错误。
Q: 可以同时处理多个订单吗？
A: 可以。系统支持并发处理多个订单，通过唯一金额匹配确保订单准确性。
🔧 技术相关
Q: 如何确保通讯安全？
A: 系统使用32位MD5密钥进行通讯验证，所有API请求都需要包含正确的密钥才能访问。
Q: 系统支持HTTPS吗？
A: 支持。推荐使用HTTPS部署，提高通讯安全性。监控端APP也支持HTTPS连接。
Q: 如何备份系统数据？
A: 主要数据存储在MySQL数据库中，定期备份数据库即可。建议同时备份上传的收款码图片。
Q: 系统支持集群部署吗？
A: 当前版本主要面向中小规模应用，暂不支持集群部署。如有大规模需求，建议进行定制开发。
📱 监控端相关
Q: 监控端APP在哪里下载？
A: 访问系统的监控端配置页面（/monitor_config.php），页面中提供了下载链接。
Q: 一个系统可以连接多个监控端吗？
A: 理论上可以，但建议只使用一个监控端，避免重复处理和冲突。
Q: 监控端需要root权限吗？
A: 不需要。监控端通过系统通知API获取收款信息，无需root权限。
🚀 使用建议
💡 最佳实践
- 使用专门的手机或模拟器运行监控端APP
- 定期检查监控端连接状态
- 设置合理的订单超时时间（建议5-30分钟）
- 配置异步通知地址，及时处理支付结果
- 定期备份系统数据和配置
- 监控系统运行日志，及时发现问题
⚠️ 注意事项
- 本系统仅供个人开发者学习测试使用
- 请勿用于大规模商业用途
- 遵守相关法律法规，合规使用
- 定期更新系统版本，修复安全漏洞
- 妥善保管通讯密钥，避免泄露