架构说明 快速开始 方式A:插件 方式B:API 异步回调 查询退款 码牌收款 加密货币收款 监控端 常见问题

系统与架构说明

本系统为 彩虹易支付协议 100% 兼容 的高性能支付网关,完全运行于 Cloudflare 全球边缘网络(非 PHP 程序,基于 Cloudflare Pages + D1 强一致数据库),杜绝原版流传源码中的恶意后门与数据库注入漏洞。

任何支持易支付协议的商城、发卡站、会员系统填入三件套参数即可开箱即用。同时原生支持 支付宝免CK官方API模式、V免签安卓原生App、桌面挂机端 与 OneBot 协议端 接入。

快速开始(三步接入)

  1. 获取商户凭据:登录 商户中心 注册账号,在主页直接获取您的商户编号 PID 与通信私钥 KEY。
  2. 配置映射通道:管理员在后台创建收款通道并启用,在系统设置中通过可视化下拉完成支付类型映射(如 alipay/wxpay/qqpay/usdt)。
  3. 接入收款:将三件套参数填入网站插件即可发起收款,无需网站时也可以直接使用码牌收款。
支付类型标识中文名称说明
alipay支付宝当面付 / 个人码账单轮询 / 免CK模式
wxpay微信支付官方扫码 Native V2 / 个人码监控
qqpayQQ 钱包QQ 钱包账单轮询 / OneBot 协议端
usdtUSDT 泰达币TRC20 链上地址收款

方式A:现成易支付插件接入(推荐)

市面上 99% 的开源商城、发卡系统(如独角数卡、WordPress WooCommerce、Typecho、Z-Blog、荔枝发卡、WHMCS 等)都内置易支付插件,只需填入以下三项:

插件配置项对应参数说明
网关 / 接口地址https://您的域名 (例如 https://epay-pages.pages.dev)
商户ID (PID)商户中心主页显示的数字 ID(例如 1)
商户密钥 (KEY)商户中心显示的 32 位通信私钥

方式B:直连 API 接口下单

自研系统或无插件场景,可向网关发起 HTTP 请求:

  • 页面跳转方式:GET / POST /submit.php(自动 302 携带参数重定向至收银台)
  • 接口返回方式:GET / POST /mapi.php(返回 JSON 结构:含 trade_no, payurl, qrcode)
参数名必填类型说明
pid是Int商户编号
type是String支付方式 (alipay / wxpay / qqpay / usdt)
out_trade_no是String商户系统唯一订单号
notify_url是String服务器异步通知完整公网 URL
return_url否String买家支付完成后同步跳转页面
name是String商品名称
money是Decimal金额(元,精确到两位小数,如 10.00)
sign是String请求数字签名
sign_type是String固定传 MD5(或商户配置的 RSA)

签名算法

将所有请求参数(排除 sign、sign_type 及空值参数)按参数名 ASCII 码升序排序,以 k=v& 拼接为待签名字符串。末尾直接拼接商户 KEY 后取 32 位小写 MD5:md5(待签字符串 + KEY)。

Node.js 下单签名示例 javascript
const crypto = require('crypto');

function buildSign(params, key) {
  const sortedKeys = Object.keys(params)
    .filter(k => k !== 'sign' && k !== 'sign_type' && params[k] !== '' && params[k] !== undefined)
    .sort();
  const queryStr = sortedKeys.map(k => k + '=' + params[k]).join('&');
  return crypto.createHash('md5').update(queryStr + key).digest('hex');
}

// 构造下单参数
const order = {
  pid: '1',
  type: 'alipay',
  out_trade_no: 'ORDER_' + Date.now(),
  notify_url: 'https://mysite.com/api/pay/notify',
  return_url: 'https://mysite.com/pay/success',
  name: '高级VIP会员月卡',
  money: '29.90',
};

const sign = buildSign(order, '您的32位商户密钥');
const payUrl = 'https://epay-pages.pages.dev/submit.php?' + new URLSearchParams({
  ...order,
  sign,
  sign_type: 'MD5'
}).toString();

console.log('请引导用户跳转此链接支付:', payUrl);
Python 下单签名示例 python
import hashlib
from urllib.parse import urlencode

def build_sign(params, key):
    filtered = sorted((k, v) for k, v in params.items() if k not in ('sign', 'sign_type') and v != '')
    query_str = '&'.join(f'{k}={v}' for k, v in filtered)
    return hashlib.md5((query_str + key).encode('utf-8')).hexdigest()

params = {
    'pid': '1',
    'type': 'wxpay',
    'out_trade_no': 'PY_1001',
    'notify_url': 'https://mysite.com/notify',
    'name': '赞助测试',
    'money': '5.00'
}
params['sign'] = build_sign(params, '商户密钥')
params['sign_type'] = 'MD5'
print('https://epay-pages.pages.dev/submit.php?' + urlencode(params))

异步回调通知与验签

买家支付成功后,网关会以 GET 请求向商户预留的 notify_url 发送异步通知。商户验签通过后,必须仅输出纯文本 success,否则系统将在 24 小时内启动重试机制(最多 5 次)。

PHP 异步通知验签处理示例 php
<?php
$key = '您的商户密钥';
$params = $_GET;
$sign = $params['sign'];

// 排序并过滤空值与签名键
ksort($params);
$signParts = [];
foreach ($params as $k => $v) {
    if ($k !== 'sign' && $k !== 'sign_type' && $v !== '') {
        $signParts[] = "$k=$v";
    }
}
$expectSign = md5(implode('&', $signParts) . $key);

if ($sign === $expectSign) {
    if ($params['trade_status'] === 'TRADE_SUCCESS') {
        $tradeNo = $params['trade_no'];       // 平台订单号
        $outTradeNo = $params['out_trade_no']; // 商户订单号
        $money = $params['money'];             // 实付金额
        
        // 执行业务发货逻辑...
    }
    // 成功处理必须原样输出小写 success
    exit('success');
} else {
    exit('fail');
}

订单查询与退款 API

API 兼容端点说明 http
# 1. 订单状态查询 (GET)
GET /api.php?act=order&pid=商户ID&key=商户KEY&trade_no=平台订单号

# 2. 订单退款 (POST 表单)
POST /api.php?act=refundapi
trade_no=平台订单号&money=退款金额&key=md5(trade_no+系统KEY+trade_no)

码牌收款模式(无网站场景)

系统为每个商户提供专属静态聚合收银码牌页面:https://您的域名/pay/商户ID。

无需搭建独立商城,直接将此链接打印成实体收银台台卡或发给买家,买家自主输入金额并选择支付渠道即可完成支付。

加密货币收款(USDT / TRC20 链上免挂)

系统内置两种 USDT 收款模式,均支持资金直接进你自己的私人钱包、无中间商抽成、无需手机常驻挂机:

模式适用场景所需配置优势
🌟 模式一:原生内置对账(强烈推荐) 不想买服务器、不想折腾 Docker、只要收 USDT 仅需一个 TRC20 钱包地址 (T开头) 纯 Cloudflare 云端边缘直连波场主网,真正零服务器、零挂机、开箱即用
模式二:自建 BEpusdt 网关 已有境外 VPS,需多公链支持或 BEpusdt 独立收银台 BEpusdt 服务地址 + API 对接令牌 独立网关架构,支持多代币/多链扩展

方式一:原生内置模式极简开通(仅需 2 步,最省心)

  1. 进「支付渠道 → 添加渠道」,插件类型选 原生USDT(TRC20链上查账·零服务器免挂),填入你的 TRC20 收款钱包地址(如交易所充币地址或个人冷热钱包),状态选启用。
  2. 进「系统设置 → 类型→渠道 映射」,添加一行:支付方式选 USDT 泰达币 (usdt),点选刚添加的渠道并保存。

执行机制:商户下单 type=usdt 时,系统自动拉取实时汇率并追加 4 位防撞单微尾数(如 13.6942 USDT);买家在收银台扫码或复制地址转账,波场主网出块后(通常 5~15 秒),系统自动检测并秒级核销订单!

方式二:外部 BEpusdt 网关对接

若自己在境外 VPS 通过 Docker 部署了 v03413/BEpusdt 独立网关:

  1. 在服务器启动:docker run -d --name bepusdt -p 8000:8000 -v /root/bepusdt:/data v03413/bepusdt:latest
  2. 进入 BEpusdt 后台配置钱包地址,在「系统管理 → 基本设置 → API 设置」复制对接令牌。
  3. 在 epay 后台渠道选 BEpusdt(加密货币),填入服务域名与对接令牌即可。

多端监控生态

客户端实现路径运行环境
安卓 Appagent/android 原生 Kotlin,自动监控系统通知安卓手机 / 云手机
桌面守护端agent/desktop/vmq_agent.py 单文件 PythonWindows / macOS / Linux
OneBot 协议端NapCat / LLOneBot HTTP 上报至 /onebot/reportQQ 机器人挂机服务器
免挂免CK后台 alipaybill 绑定开放平台官方 APPID 密钥Cloudflare 云端无感对账

常见接入问题

  1. 签名错误:请核对是否过滤了空参数、是否包含 sign 与 sign_type,以及字母排序是否遵循严格的 ASCII 码升序。
  2. 收不到回调通知:请确保 notify_url 是公网可解析的有效地址,不能为 localhost 或带内网 IP。
  3. 响应格式:商户接收到通知处理完毕后,HTTP 响应内容必须为纯文本字符串 success,不可附加 HTML 标签或换行。