EPay 协议接入文档 — 188Pay 加密货币支付网关

网关地址

接入前请确认网关基础地址

🌐

网关基础地址：https://api2.188pay.top
创建订单端点：POST / GET /submit.php

独角数卡 填写完整地址：https://api2.188pay.top/submit.php
V2Board / SSPanel 仅填写根域名：https://api2.188pay.top

创建订单

向 188Pay 提交订单，跳转到收银台页面

发起 POST 或 GET 请求到：

URL

# 主端点（推荐，与标准 EPay 完全兼容）
https://api2.188pay.top/submit.php

# 等效别名（均可使用）
https://api2.188pay.top/epay/submit
https://api2.188pay.top/epay/submit.php

参数名	类型	必填	说明
pid	string	必填	商户 ID，在「API 密钥」页面获取
type	string	必填	支付币种：`usdt`（USDT TRC20，默认） / `trx`（TRX） / `fiat_alipay`（支付宝收款）
out_trade_no	string	必填	商户订单号，您系统内唯一的订单 ID
money	string	必填	订单金额，按系统配置币种计价（如 CNY 或 USDT）
notify_url	string	必填	支付成功后的异步回调地址，必须为外网可访问地址
return_url	string	可选	支付完成后跳转回您网站的地址
name	string	可选	商品/订单标题，显示在收银台页面
sign	string	必填	MD5 签名，见下方签名算法章节

HTML 表单提交示例：

HTML

<form action="https://api2.188pay.top/submit.php" method="POST">
  <input type="hidden" name="pid"          value="your_merchant_id">
  <input type="hidden" name="type"         value="usdt">
  <input type="hidden" name="out_trade_no" value="ORDER_20260224_001">
  <input type="hidden" name="money"        value="10.00">
  <input type="hidden" name="name"         value="会员套餐">
  <input type="hidden" name="notify_url"  value="https://your-site.com/payment/notify">
  <input type="hidden" name="return_url"  value="https://your-site.com/order/success">
  <input type="hidden" name="sign"         value="<?php echo $sign; ?>">
  <button type="submit">立即支付</button>
</form>

↩

响应：成功提交后，服务器将返回 302 跳转，将用户重定向到 188Pay 收银台页面。用户在收银台完成链上转账后，系统自动检测并回调 notify_url。

回调通知

支付成功后 188Pay 主动通知您的服务器

链上交易确认后，系统将发起 GET 请求到 notify_url，参数通过 URL 查询字符串传递。

参数名	类型	说明
pid	string	商户 ID
trade_no	string	188Pay 平台订单号
out_trade_no	string	商户订单号（即您创建订单时传入的值）
money	string	订单金额（与创建时一致）
type	string	支付币种：`usdt` / `trx` / `fiat_alipay`
trade_status	string	支付状态：固定为 `TRADE_SUCCESS`（支付成功），回调仅在支付成功时发送
sign	string	MD5 签名，用于验证回调真实性
sign_type	string	签名类型，固定值 `MD5`

✅

回调处理要求（重要）：
1. 先验证 sign 签名，确保请求来自 188Pay
2. 确认 trade_status == TRADE_SUCCESS 再执行业务逻辑（发货/开通服务）
3. 处理完成后返回 HTTP 200，响应体为纯文本 success 或 ok
4. 不要在响应中输出 HTML 页面或其他内容，否则视为失败并触发重试

🔄

自动重试机制：若回调未收到有效响应，系统将按指数退避策略最多重试 6 次： 15s → 30s → 1min → 2min → 4min → 8min。全部失败后可在「回调记录」页面手动重发。

签名算法

EPay 模式签名规则，与标准模式的区别在于密钥追加方式

1

构造签名参数字符串

将所有参数（除 sign 和 sign_type 外）按参数名 ASCII 升序排列，过滤值为空的参数，拼接为 key=value&key=value 格式。

签名字符串示例

# 原始参数（按 ASCII 升序排列，过滤空值，排除 sign/sign_type）
money=10.00&name=会员套餐&notify_url=https://your-site.com/payment/notify&out_trade_no=ORDER_20260224_001&pid=your_merchant_id&type=usdt

2

追加密钥并计算 MD5

在签名字符串末尾直接追加密钥（EPay 模式，无 &key= 前缀），然后对整个字符串计算 MD5，结果转为小写 hex。

⚠️

EPay 模式与标准模式的关键区别：
EPay 模式：签名字符串 + 密钥（直接追加，无分隔符）
标准 API 模式：签名字符串 + &key= + 密钥（带 &key= 前缀）

完整签名示例

# 步骤 1: 参数按 ASCII 排序拼接（排除 sign/sign_type，过滤空值）
$str = "money=10.00&name=会员套餐&notify_url=https://your-site.com/payment/notify&out_trade_no=ORDER_20260224_001&pid=your_merchant_id&type=usdt"

# 步骤 2: 直接追加密钥（EPay 模式，无 &key= 前缀）
$str = $str . "your_secret_key"

# 结果:
"money=10.00&name=会员套餐&notify_url=https://your-site.com/payment/notify&out_trade_no=ORDER_20260224_001&pid=your_merchant_id&type=usdtyour_secret_key"

# 步骤 3: 计算 MD5，转小写
$sign = strtolower(md5($str))

PHP 签名函数完整示例：

PHP

/**
 * 188Pay EPay 模式签名函数
 *
 * @param array  $params     请求参数数组
 * @param string $secretKey  商户密钥
 * @return string            MD5 签名（小写）
 */
function epaySign($params, $secretKey) {
    // 1. 排除 sign、sign_type 字段，过滤空值
    $data = array_filter($params, function($v, $k) {
        return $k !== 'sign' && $k !== 'sign_type' && $v !== '' && $v !== null;
    }, ARRAY_FILTER_USE_BOTH);

    // 2. 按 ASCII（字典）升序排序
    ksort($data);

    // 3. 拼接 key=value&key=value 格式
    $str = http_build_query($data);

    // 4. EPay 模式：直接追加密钥（无 &key= 前缀）
    $str .= $secretKey;

    // 5. MD5 转小写
    return strtolower(md5($str));
}

// 使用示例
$params = [
    'pid'          => 'your_merchant_id',
    'type'         => 'usdt',
    'out_trade_no' => 'ORDER_20260224_001',
    'money'        => '10.00',
    'name'         => '会员套餐',
    'notify_url'   => 'https://your-site.com/payment/notify',
    'return_url'   => 'https://your-site.com/order/success',
];

$params['sign'] = epaySign($params, 'your_secret_key');

// 使用表单 POST 跳转或服务端发起请求

支持平台

所有兼容易支付协议的平台均可直接对接

平台	配置说明
独角数卡已支持	后台 → 支付配置 → 易支付。商户 KEY 填 `https://api2.188pay.top/submit.php`，商户 ID 和密钥照填即可。图文教程 →
V2Board 已支持	管理员 → 支付配置 → 添加易支付。网关地址填 `https://api2.188pay.top`（仅根域名，不含 /submit.php）。
SSPanel 已支持	管理员 → 支付设置 → 易支付。网关地址填 `https://api2.188pay.top`，填入商户 ID 和密钥。
WHMCS 已支持	安装易支付 WHMCS 模块，将网关地址配置为 `https://api2.188pay.top`，填入商户 ID 和密钥。
风铃发卡已支持	系统设置 → 支付接口 → 易支付。网关地址填 `https://api2.188pay.top`，填入商户 ID 和密钥。
ZFAKA 已支持	系统设置 → 支付方式 → 易支付接口。配置方式与标准易支付一致，网关填 `https://api2.188pay.top`。
鲸发卡已支持	支付配置 → 易支付。填写商户 ID、密钥，网关地址填 `https://api2.188pay.top`。
自研系统已支持	参照本文档实现 EPay 协议，或使用标准 JSON API 接入，灵活性更高。

💡

网关地址配置差异说明：
独角数卡：「商户 KEY」字段直接作为 form 提交地址，必须填写完整的 https://api2.188pay.top/submit.php，包含路径。
V2Board / SSPanel 等：框架内部会自动拼接 /submit.php，只需填写根域名 https://api2.188pay.top，不要带路径。

188Pay EPay 接入文档

网关地址

创建订单

回调通知

签名算法

支持平台