聚合支付对接文档

01通用规则

商户 ID 与密钥在「开通邮件」里；如果你是通过第三方系统接入，把上面这两个地址分别填到「接口地址 / 网关地址」即可，程序会自动拼后面的路径。

02签名算法（最关键的一步）

九成「签名错误」都出在下面四条里，逐条对：

// 待签名参数（sign / sign_type 不参与）
money=10.10
name=VIP会员
notify_url=https://your.site/notify.php
out_trade_no=ORD20261108001
pid=1001
return_url=https://your.site/return.php
type=alipay

// 按 ASCII 升序拼成一串（值不编码），末尾直接接 KEY
money=10.10&name=VIP会员&notify_url=https://your.site/notify.php&out_trade_no=ORD20261108001&pid=1001&return_url=https://your.site/return.php&type=alipay你的64位商户密钥

// 对这个整体做 MD5，取小写

03页面跳转支付（主流程）

用户点「去支付」时，浏览器直接跳到下面这个地址，我们接住后 302 到收银台（支付宝 / 微信）。

GET /ypay/submit.php
  ?pid=1001
  &type=alipay
  &out_trade_no=ORD20261108001
  &money=10.10
  &name=VIP会员
  &notify_url=https://your.site/notify.php
  &return_url=https://your.site/return.php
  &sign=8f14e45fceea167a5a36dedd4bea2543
  &sign_type=MD5

04异步通知（到账的唯一依据）

用户付款成功后，我们的服务器会以 GET 方式请求你填的 notify_url。收到后先验签、再改单、最后返回纯文本 success。

回调可能重复、也可能延迟，因此你的处理必须幂等：已处理的订单直接返回 success。回调没到时，用第 05 节的查单接口补一次，不要只依赖回调。

05查单（掉单补查）

GET https://vorbynsnty.kdns.fr/ypay/mapi.php
  ?pid=1001
  &key=你的64位商户密钥
  &out_trade_no=ORD20261108001

查单用 key 直接校验（不走 sign），所以这个接口只能在你自己的服务器上调用，别把密钥放进前端代码。

06代码示例

以 PHP 为例（大多数发卡 / 虚拟商品系统都是 PHP）；Node.js 与 Python 只差一个排序拼接。

// 1) 发起支付：拼参数 → 排序 → 签名 → 跳转
$pid = '1001';
$key = '你的64位商户密钥';
$p = array(
    'pid'          => $pid,
    'type'         => 'alipay',
    'out_trade_no' => 'ORD' . date('YmdHis') . mt_rand(1000, 9999),
    'money'        => '10.10',
    'name'         => 'VIP会员',
    'notify_url'   => 'https://your.site/notify.php',
    'return_url'   => 'https://your.site/return.php',
);
ksort($p);                        // ① ASCII 升序
$s = array();
foreach ($p as $k => $v) { $s[] = $k . '=' . $v; }   // ② 值不做 urlencode
$p['sign'] = md5(implode('&', $s) . $key);        // ③ 末尾直接接 KEY
$p['sign_type'] = 'MD5';
header('Location: https://vorbynsnty.kdns.fr/ypay/submit.php?' . http_build_query($p));
exit;


// 2) 收回调：验签 → 比金额 → 幂等改单 → 输出 success
$key = '你的64位商户密钥';
$g = $_GET;                       // 我们也可能用 POST，生产环境请合并 $_GET + $_POST
$sign = $g['sign'] ?? '';
unset($g['sign'], $g['sign_type']);
$g = array_filter($g, function ($v) { return $v !== ''; });
ksort($g);
$a = array();
foreach ($g as $k => $v) { $a[] = $k . '=' . $v; }
if (!hash_equals(md5(implode('&', $a) . $key), $sign)) { exit('fail'); }
if (($g['trade_status'] ?? '') !== 'TRADE_SUCCESS') { exit('fail'); }

// 这里务必校验：订单存在、金额一致、未处理过
// $order = find_order($g['out_trade_no']);
// if (!$order || $order['money'] != $g['money'] || $order['paid']) exit('success');
// mark_paid($order['id'], $g['trade_no']);
echo 'success';

Node.js 签名：

const crypto = require('crypto');
const sign = crypto.createHash('md5')
  .update(Object.keys(p).sort().map(k => `${k}=${p[k]}`).join('&') + key)
  .digest('hex');

Python 签名：

import hashlib
raw = '&'.join('%s=%s' % (k, p[k]) for k in sorted(p) if p[k] != '')
sign = hashlib.md5((raw + key).encode('utf-8')).hexdigest()

07排错对照表

08费率与结算

09商户查询接口（对账用）

除下单与回调外，我们还开放了一组 只读查询接口，供你在自己的后台或脚本里拉账户、订单和结算数据， 不必登录收银台后台。地址统一为 https://vorbynsnty.kdns.fr/api.php?r=接口名。

鉴权：uid + sign

每个接口都必须带 uid（你的商户 ID）和 sign，签名规则与下单完全相同： 除 sign / sign_type 外的非空参数，按参数名 ASCII 升序拼成 k=v&k=v（值不 urlencode）， 末尾直接接你的 64 位密钥，MD5 取小写。GET 与 POST（表单或 JSON）都支持，参数一并参与签名。

// PHP 示例：查账户概览
$uid = '1001';
$key = '你的64位商户密钥';
$p   = array('uid' => $uid);
ksort($p);
$str = urldecode(http_build_query($p));   // 值不做 urlencode，所以 decode 回来
$sign = md5($str . $key);

$url = 'https://vorbynsnty.kdns.fr/api.php?r=agg%2Fapi%2Faccount'
     . '&uid=' . $uid . '&sign=' . $sign;
echo file_get_contents($url);

接口一览

订单字段

返回示例

{
  "uid": "1001",
  "code": "VB5C1338CBF8",
  "name": "示例商户",
  "rate": 3.0,
  "state": "正常",
  "expire_at": "2027-11-08 23:59:59",
  "channels": ["微信支付", "支付宝"],
  "cashier_url": "https://vorbynsnty.kdns.fr/ypay/public/index.php?s=/cashier/VB5C1338CBF8",
  "total": { "count": 128, "income": 6800.00, "refund": 60.00, "fee": 202.20, "net": 6537.80 },
  "today": { "count": 6, "income": 320.00, "refund": 0.00, "fee": 9.60, "net": 310.40 },
  "settleable": 6227.40,
  "pending": 310.40,
  "server_time": "2026-11-09 07:40:00",
  "ok": true
}

结算口径

T+1：当天的成功收款计入 pending（待结算），次日进入 settleable（可结算），由平台统一打款。 手续费按 money - refund 乘你的费率计算，退款部分不计费。 agg/api/settle 返回的每日记录里，昨天及更早的日期标记为「已结算」，当天的标记为「待结算」。

错误码

这组接口是只读的：不能下单、不能退款、不能改配置。退款与提现请在收银台后台操作，或联系客服。 查询接口有频率限制，轮询对账建议 5 分钟一次，不要每秒拉全量。

10平台性质与底层渠道

Vorbyn Pay 是一套聚合支付技术工具：它把你的订单统一起来，转发给上游支付渠道完成收款， 再把渠道的回调结果通知给你。本平台不持牌、不清算、不沉淀资金——钱从付款人直接进入渠道账户， 由渠道方完成清算与结算。我们负责的是下单、签名、验签、对账与排障。

实际收款与结算由谁完成

你能在渠道后台看到什么

开通后，除了本平台的商户中心，你还会拿到上面两个渠道后台的登录方式（在商户中心「渠道说明」里）， 用它可以自己核对每一笔订单、到账金额与结算记录。两边数据不一致时，以渠道后台为准——平台页面只是汇总展示。

合规边界