VibePay API 接入文档
个人免签约收款解决方案 · 基于 HTTP 接口的即时到账通知
一、简介
VibePay 是一套免签支付程序,收款即时到账,无需进入第三方账户。客户端(安卓监控端)监听微信/支付宝收款通知栏消息并上报到服务端,服务端据此向你的业务系统推送支付结果。
- 所有接口均支持
GET与POST方式调用。 - 请求与响应均为
application/x-www-form-urlencoded(参数)与application/json(响应)。 - 响应统一结构:
{"code":1,"msg":"成功","data":{...}},code=1表示成功,code=-1表示失败。 - 请务必在 管理后台 → 系统设置 中配置你的「通讯密钥」与「异步通知地址 / 同步跳转地址」。
安全提示:通讯密钥等同于你的接口密码,切勿硬编码在前端代码或公开仓库中。所有涉及资金变动的回调,必须校验签名。
二、签名(sign)规则
所有写操作(创建订单、关闭订单、查询状态)都需要签名,用于验证请求来源。签名统一使用 MD5(小写32位) 拼接计算。
| 接口 | 签名拼接串(按顺序直接拼接,无分隔符) |
|---|---|
| /createOrder | md5(payId + param + type + price + key) |
| /closeOrder | md5(orderId + key) |
| /getState | md5(t + key) |
| 回调通知 | md5(payId + param + type + price + reallyPrice + key) |
其中 key 为你的通讯密钥;param 为空时传空字符串 ""(仍参与拼接)。计算完成后请将签名转为 小写 后随参数一起发送。
# 以创建订单为例,参数如下:
payId = 1547129707139
param = vone666
type = 2
price = 0.1
key = a7cc8678193ee9c70ae3d75fd04ae6a9
拼接串 = "1547129707139" + "vone666" + "2" + "0.1" + "a7cc8678193ee9c70ae3d75fd04ae6a9"
= "1547129707139vone66620.1a7cc8678193ee9c70ae3d75fd04ae6a9"
sign = md5(拼接串) = "2b8b5d58c51203162f14939bdbc46a54"
payId = 1547129707139
param = vone666
type = 2
price = 0.1
key = a7cc8678193ee9c70ae3d75fd04ae6a9
拼接串 = "1547129707139" + "vone666" + "2" + "0.1" + "a7cc8678193ee9c70ae3d75fd04ae6a9"
= "1547129707139vone66620.1a7cc8678193ee9c70ae3d75fd04ae6a9"
sign = md5(拼接串) = "2b8b5d58c51203162f14939bdbc46a54"
三、创建订单
地址:
/createOrder
方式:POST / GET
签名:md5(payId+param+type+price+key)
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| payId | String | 【必传】商户订单号,建议时间戳,不可重复 |
| type | Int | 【必传】1=微信 2=支付宝 |
| price | Decimal | 【必传】订单金额,大于 0 |
| sign | String | 【必传】见签名规则 |
| param | String | 【可选】透传参数,原样返回至回调 |
| isHtml | Int | 【可选】1=跳转支付页 0=返回 JSON(默认 0) |
| notifyUrl | String | 【可选】异步通知地址,覆盖后台设置 |
| returnUrl | String | 【可选】支付完成后同步跳转地址 |
返回示例(isHtml=0)
{
"code": 1,
"msg": "成功",
"data": {
"payId": "1547129707139",
"orderId": "201901102220147500",
"payType": 2,
"price": 0.1,
"reallyPrice": 0.1,
"payUrl": "HTTPS://QR.ALIPAY.COM/FKX0...",
"isAuto": 1,
"state": 0,
"timeOut": 5,
"date": 1547130014777
}
}
data 字段说明
| payId | 商户订单号 |
| orderId | 云端订单号,用于查单 |
| payType | 1=微信 2=支付宝 |
| payUrl | 支付二维码内容(自行生成二维码) |
| isAuto | 1=需手动输金额 0=扫码自动填金额 |
| state | -1过期 0待付 1完成 2完成但通知失败 |
| timeOut | 订单有效时间(分钟) |
四、查询订单信息
地址:
/getOrder
方式:POST / GET
签名:无需
| 参数 | 类型 | 说明 |
|---|---|---|
| orderId | String | 【必传】云端订单号(创建订单时返回) |
返回结构与「创建订单」的 data 一致,可用于轮询订单状态。
五、查询订单状态(校验是否支付)
地址:
/checkOrder
方式:POST / GET
签名:无需
| 参数 | 类型 | 说明 |
|---|---|---|
| orderId | String | 【必传】云端订单号 |
{
"code": 1,
"msg": "成功",
"data": "https://your-domain/callback?payId=...¶m=...&type=2&price=0.1&reallyPrice=0.1&sign=..."
}
code=1:订单已支付成功,data为支付完成后的跳转地址(带回调参数)。code=-1:未支付或支付失败,data为 null,具体原因见msg。
六、关闭订单
地址:
/closeOrder
方式:POST / GET
签名:md5(orderId+key)
| 参数 | 类型 | 说明 |
|---|---|---|
| orderId | String | 【必传】云端订单号 |
| sign | String | 【必传】md5(orderId + 通讯密钥) |
{
"code": 1,
"msg": "成功",
"data": null
}
code=1 关闭成功;code=-1 关闭失败,详见 msg。
七、查询服务端 / 监控端状态
地址:
/getState
方式:POST / GET
签名:md5(t+key)
| 参数 | 类型 | 说明 |
|---|---|---|
| t | Long | 【必传】当前时间戳(13位) |
| sign | String | 【必传】md5(t + 通讯密钥) |
{
"code": 1,
"msg": "成功",
"data": {
"lastpay": "1547394640856",
"lastheart": "1547613873755",
"state": "1"
}
}
| lastpay | 最后一次监控到收款的时间戳(13位) |
| lastheart | 监控端最后一次心跳时间戳(13位) |
| state | 1=监控端在线 0=掉线 -1=未绑定 |
八、回调通知说明
当用户完成付款、监控端上报后,服务端会向你在后台配置的 异步通知地址(notifyUrl) 发起 GET 请求,通知订单收款成功。若创建订单时传 isHtml=1,支付完成后还会携带参数跳转到你的 同步跳转地址(returnUrl)。
| 参数 | 类型 | 说明 |
|---|---|---|
| payId | String | 商户订单号 |
| param | String | 创建订单时传入的透传参数 |
| type | Int | 1=微信 2=支付宝 |
| price | Decimal | 订单金额 |
| reallyPrice | Decimal | 实际支付金额 |
| sign | String | md5(payId+param+type+price+reallyPrice+key) |
回调处理要求:
- 必须先校验
sign,校验通过后再处理业务,防止伪造请求。 - 处理完成后必须原样输出
success(不含多余字符),否则服务端会认为通知失败并重复推送。 - 请做好幂等处理:同一
payId可能因网络重试被多次通知。
九、多语言接入 SDK 示例
下面给出完整的「创建订单 → 处理异步回调」示例,涵盖 5 种常用语言。请将 API_BASE 与 KEY 替换为你自己的地址与通讯密钥。
<?php
// ===== 配置 =====
$API_BASE = "http://localhost:8080";
$KEY = "a7cc8678193ee9c70ae3d75fd04ae6a9"; // 通讯密钥
// ===== 1. 创建订单 =====
function createOrder($payId, $type, $price, $param = "") {
global $API_BASE, $KEY;
$sign = md5($payId . $param . $type . $price . $KEY);
$query = http_build_query([
"payId" => $payId, "type" => $type, "price" => $price,
"param" => $param, "sign" => $sign, "isHtml" => 0
]);
$res = file_get_contents("$API_BASE/createOrder?$query");
return json_decode($res, true);
}
$order = createOrder((string)time(), 2, "0.1", "vone666");
if ($order["code"] === 1) {
$payUrl = $order["data"]["payUrl"]; // 支付二维码内容
$orderId = $order["data"]["orderId"]; // 云端订单号
echo "请扫码支付:$payUrl\n";
}
// ===== 2. 异步回调处理(notifyUrl 指向的脚本) =====
$key = $KEY;
$payId = $_GET['payId'];
$param = $_GET['param'];
$type = $_GET['type'];
$price = $_GET['price'];
$reallyPrice = $_GET['reallyPrice'];
$sign = $_GET['sign'];
$_sign = md5($payId . $param . $type . $price . $reallyPrice . $key);
if ($_sign !== $sign) {
echo "error_sign"; exit;
}
// TODO: 处理你的业务(注意幂等)
echo "success";
?>