VibePay 管理后台

VibePay API 接入文档

个人免签约收款解决方案 · 基于 HTTP 接口的即时到账通知

一、简介

VibePay 是一套免签支付程序,收款即时到账,无需进入第三方账户。客户端(安卓监控端)监听微信/支付宝收款通知栏消息并上报到服务端,服务端据此向你的业务系统推送支付结果。

  • 所有接口均支持 GETPOST 方式调用。
  • 请求与响应均为 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"

三、创建订单

地址:/createOrder 方式:POST / GET 签名:md5(payId+param+type+price+key)

请求参数

参数类型说明
payIdString【必传】商户订单号,建议时间戳,不可重复
typeInt【必传】1=微信 2=支付宝
priceDecimal【必传】订单金额,大于 0
signString【必传】见签名规则
paramString【可选】透传参数,原样返回至回调
isHtmlInt【可选】1=跳转支付页 0=返回 JSON(默认 0)
notifyUrlString【可选】异步通知地址,覆盖后台设置
returnUrlString【可选】支付完成后同步跳转地址

返回示例(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云端订单号,用于查单
payType1=微信 2=支付宝
payUrl支付二维码内容(自行生成二维码)
isAuto1=需手动输金额 0=扫码自动填金额
state-1过期 0待付 1完成 2完成但通知失败
timeOut订单有效时间(分钟)

四、查询订单信息

地址:/getOrder 方式:POST / GET 签名:无需
参数类型说明
orderIdString【必传】云端订单号(创建订单时返回)

返回结构与「创建订单」的 data 一致,可用于轮询订单状态。

五、查询订单状态(校验是否支付)

地址:/checkOrder 方式:POST / GET 签名:无需
参数类型说明
orderIdString【必传】云端订单号
{
  "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)
参数类型说明
orderIdString【必传】云端订单号
signString【必传】md5(orderId + 通讯密钥)
{
  "code": 1,
  "msg": "成功",
  "data": null
}

code=1 关闭成功;code=-1 关闭失败,详见 msg

七、查询服务端 / 监控端状态

地址:/getState 方式:POST / GET 签名:md5(t+key)
参数类型说明
tLong【必传】当前时间戳(13位)
signString【必传】md5(t + 通讯密钥)
{
  "code": 1,
  "msg": "成功",
  "data": {
    "lastpay": "1547394640856",
    "lastheart": "1547613873755",
    "state": "1"
  }
}
lastpay最后一次监控到收款的时间戳(13位)
lastheart监控端最后一次心跳时间戳(13位)
state1=监控端在线 0=掉线 -1=未绑定

八、回调通知说明

当用户完成付款、监控端上报后,服务端会向你在后台配置的 异步通知地址(notifyUrl) 发起 GET 请求,通知订单收款成功。若创建订单时传 isHtml=1,支付完成后还会携带参数跳转到你的 同步跳转地址(returnUrl)

参数类型说明
payIdString商户订单号
paramString创建订单时传入的透传参数
typeInt1=微信 2=支付宝
priceDecimal订单金额
reallyPriceDecimal实际支付金额
signStringmd5(payId+param+type+price+reallyPrice+key)
回调处理要求:
  • 必须先校验 sign,校验通过后再处理业务,防止伪造请求。
  • 处理完成后必须原样输出 success(不含多余字符),否则服务端会认为通知失败并重复推送。
  • 请做好幂等处理:同一 payId 可能因网络重试被多次通知。

九、多语言接入 SDK 示例

下面给出完整的「创建订单 → 处理异步回调」示例,涵盖 5 种常用语言。请将 API_BASEKEY 替换为你自己的地址与通讯密钥。

<?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";
?>