VibePay 开放接口文档

快速开始

1. 注册并登录管理后台，在 应用接入 页面获取 Corporate ID 与 Corporate Secret。
2. 在应用接入页新增一个应用，获得该应用的 App ID。
3. 在 二维码管理 上传你的微信/支付宝收款二维码（可固定金额）。
4. 调用 /createOrder 创建订单，将返回的收款图展示给用户。
5. 用户扫码付款后，监控端自动上报，系统向你配置的 notifyUrl 推送到账通知。

接入凭证（三要素）

接入 VibePay 需要三个凭证，均可在 管理后台 → 应用接入 页面获取：

每个公司、每个应用的凭证均不相同，请使用你自己后台显示的凭证（本文档中的取值仅为格式示例，非真实可用凭证）。

签名规则

所有写操作（创建订单、关闭订单、状态上报等）都需要签名校验，防止参数被篡改。签名统一使用 md5(拼接串)，结果取 32 位小写十六进制。

各接口的拼接串

创建订单签名示例

payId    = 1547129707139
param    = vibeadmin123
type     = 2
price    = 0.1
secret   = a7cc8678193ee9c70ae3d75fd04ae6a9

拼接串 = "1547129707139" + "vibeadmin123" + "2" + "0.1" + "a7cc8678193ee9c70ae3d75fd04ae6a9"
        = "1547129707139vibeadmin12320.1a7cc8678193ee9c70ae3d75fd04ae6a9"
sign     = md5(拼接串)  // 32 位小写十六进制

POST 创建订单 /createOrder

创建一个收款订单，返回云端订单号、收款二维码内容（payUrl）与收款图地址。

请求参数（表单 / x-www-form-urlencoded）

返回示例（isHtml=0）

{
  "code": 1,
  "msg": "成功",
  "data": {
    "payId": "1547129707139",
    "orderId": "20240719120000abcd",
    "type": 2,
    "price": 0.1,
    "reallyPrice": 0.1,
    "payUrl": "wxp://xxxxx 或 alipay://xxxxx",
    "isAuto": 0,
    "state": 0,
    "timeOut": 5
  }
}

state：0=待支付，-1=已过期，1=已支付。reallyPrice 为实际匹配到的二维码金额（可能与 price 存在 ±0.01 的浮动）。

POST 查询订单 /getOrder

根据云端订单号查询订单详情。

POST /getOrder
orderId=20240719120000abcd

返回结构与创建订单一致，关注 state 字段：0=待支付，-1=已过期，1=已支付。

POST 校验订单状态 /checkOrder

校验订单支付状态，已支付则返回同步回调跳转地址（returnUrl + 参数 + sign）。

POST /checkOrder
orderId=20240719120000abcd

• state=0：返回"订单未支付"
• state=-1：返回"订单已过期"
• state=1：返回 returnUrl?payId=...¶m=...&type=...&price=...&reallyPrice=...&sign=...

POST 关闭订单 /closeOrder

主动关闭一笔待支付订单，释放金额占位。

POST /closeOrder
orderId=20240719120000abcd
sign=md5(orderId + secret)

POST 服务端状态 /getState

监控端心跳使用，返回监控端在线状态（jkstate）、最近心跳时间、最近付款时间。签名：md5(t + secret)，其中 t 为当前时间戳（毫秒）。

POST /getState
t=1721376000000
sign=md5(t + secret)

监控端相关接口（/appHeart、/appPush）属于手机 App 内部调用，/appPush 签名为 md5(type + price + t + secret)。三方系统一般无需直接调用。

回调说明

异步回调（notifyUrl）

订单支付成功后，系统向你在应用或公司配置的 notifyUrl 发起 GET 回调：

https://your-domain.com/callback?payId=...¶m=...&type=2&price=0.1&reallyPrice=0.1&sign=...&appId=...

你的服务端需校验 sign（拼接串 payId+param+type+price+reallyPrice+secret 重算比对），校验通过后返回纯文本 success，系统才会标记通知成功；否则会按策略重试。

同步回调（returnUrl）

用户支付完成后可被引导回 returnUrl，参数同上，用于前端展示支付结果。

会员体系

平台提供内置会员体系。租户需开通会员后才能使用下单（/createOrder）、监控端心跳（/appHeart）、监控端上报（/appPush）等收款功能；管理员角色与平台收款租户不受此限制。

会员充值完全复用本系统的支付通道：商户在后台「会员管理」选择套餐（月度 / 季度 / 年费 / 三年，具体价格与时长以后台返回为准，可在服务端 application.yml 的 app.member.plans 配置）后，系统自动以平台收款租户身份调用 /createOrder 创建订单（归属平台默认应用），商户扫码付款，平台监控端上报后自动开通 / 续费。

应用接入模型

VibePay 采用「公司（Corporate）→ 应用（App）」两级模型：

• 公司：对应一个注册账号（租户），拥有唯一的 Corporate ID 与 Secret。
• 应用：公司下可创建多个应用，每个应用有独立的 App ID、收款二维码与回调地址；订单按应用维度隔离与统计。
• 调用接口时必须同时携带 corporateId 与 appId，订单归属到对应应用。

多语言 SDK 示例

以下示例演示如何计算签名并创建订单。Secret 请替换为你的 Corporate Secret（拼接串为 payId+param+type+price+secret）。

常见问题