图文配置教程 · 4步完成

188Pay ZFAKA 发卡接入指南

上传 188Pay 专属插件，简单配置即可收款
加密货币（USDT TRC20 / TRX）+ 法币（支付宝 / 微信），款项直达你的钱包

ZFAKA v1.4.x

加密 epay188

法币 epay188alipay

协议 EPay 易支付

支持 USDT · TRX · 支付宝 · 微信

⚠️

注意 · 图示仅供参考

本教程中的界面截图为示意图，展示的是配置流程的大概位置与步骤。由于 ZFAKA 版本迭代，实际界面样式、字段名称或菜单位置可能与图示有所不同，请以你实际使用的版本为准。如遇到差异或配置问题，欢迎联系 Telegram @token188 获取支持。

📋

开始前准备

已安装 ZFAKA 发卡系统（v1.4.x）
已注册 188Pay 商户账号并添加了收款钱包
拥有 ZFAKA 服务器的 SSH 或 FTP 访问权限

准备工作

获取 188pay 商户凭证商户ID + 密钥 + 网关地址

🔒www.188pay.top/dashboard/api-keys ↗ 点击直达

API 密钥

① 复制商户 ID → 填入 ZFAKA「商户ID」字段

              620f22b6-56a8-4ac8-a5ff-a257bcb1d84b
            

② 复制密钥 → 填入 ZFAKA「商户密钥」字段

••••••••••••••••••••••••••••••••••

③ 复制网关地址 → 填入 ZFAKA「网关地址」字段

              https://api2.188pay.top
            

ZFAKA 插件使用此地址，不需要加 /submit.php

🔗

直接访问 www.188pay.top/dashboard/api-keys 复制 商户ID、密钥和网关地址，Step 03 填写 ZFAKA 配置时需要用到。

第一步

安装 188Pay 插件上传文件 + 一键安装

Terminal — SSH

# 进入 ZFAKA 安装目录
cd /你的zfaka目录

# 克隆 188Pay 插件
git clone https://github.com/utgpay2/zfakausdt.git /tmp/zfakausdt

# 复制插件文件到 ZFAKA
cp -r /tmp/zfakausdt/application/* application/
cp -r /tmp/zfakausdt/public/* public/

# 设置文件权限（两个通道都要设）
chmod 755 application/library/Pay/epay188/epay188.php
chmod 755 application/library/Pay/epay188alipay/epay188alipay.php

# 运行一键安装脚本（直接命令行执行，无需浏览器访问）
php /tmp/zfakausdt/install_188pay.php
# ⚠️ 安装完成后删除脚本
rm install_188pay.php

🚀 一键安装（推荐）

脚本会自动读取 ZFAKA 数据库配置，插入两条支付渠道记录（USDT + 支付宝）：

          php install_188pay.php
        

推荐命令行执行，部分 nginx 配置会把 .php 请求重写到 ZFAKA 首页导致浏览器访问 404。如果命令行不可用，也可以在宝塔面板「终端」里执行。
⚠️ 安装完成后请立即删除 install_188pay.php！

📁 插件文件结构

application/library/Pay/
├── epay188/
│   └── epay188.php          ← USDT/TRX
└── epay188alipay/
    └── epay188alipay.php    ← 支付宝
modules/.../tpl/
├── epay188.html
└── epay188alipay.html

🔧 手动安装（备选）

如需手动安装，执行两条 SQL：

-- ① USDT/TRX 通道
INSERT INTO t_payment (payment, payname,
  alias, configure3, configure4, ...)
VALUES ('188Pay', '188Pay USDT/TRX',
  'epay188', 'https://api2.188pay.top',
  'usdt', ...);
-- ② 支付宝通道
INSERT INTO t_payment (payment, payname,
  alias, configure3, configure4, ...)
VALUES ('188Pay', '188Pay 支付宝',
  'epay188alipay', 'https://api2.188pay.top',
  'alipay', ...);
-- 完整 SQL 见 install.sql

💡

插件源码在 GitHub：github.com/utgpay2/zfakausdt。如果没有 SSH 权限，也可以通过 FTP 手动上传文件。手动执行 SQL 可使用 phpMyAdmin 等数据库管理工具。

⚠️

重要：插件别名（alias）不能含下划线

ZFAKA 使用 Yaf 框架，Yaf 的自动加载器遵循 PSR-0 规范，会把类名里的 _ 当成目录分隔符。比如 alias 写成 epay188_alipay，Yaf 会去找 Pay/epay188/alipay/epay188/alipay.php，找不到就报 500。
所以两个插件别名必须用：epay188（USDT/TRX）和 epay188alipay（支付宝），绝不能加下划线。

第二步

确认站点地址 (weburl)设置中心 → 配置中心 → weburl

🔒your-shop.com/goadmin/configure/edit/weburl

配置中心

编辑

配置名

weburl

值

http://你的域名:端口

备注

当前网站地址,用于支付站点异步返回，务必修改正确

确认修改

⚠️ 关键！末尾不要带斜杠

http://example.com:8080/ ✗
http://example.com:8080 ✓

💡 为什么 weburl 很重要？

ZFAKA 用此地址拼接回调 URL：
weburl + /product/notify/?paymethod=epay188

💡

在「设置中心 → 配置中心」找到 weburl 配置项，点击「编辑」。填入正确的站点地址（含端口），末尾不要带 /，否则回调 URL 会出现双斜杠导致 404。

第三步

配置 188Pay 支付参数支付设置 → 编辑 188Pay

🔒your-shop.com/goadmin/payment/edit/188Pay

支付设置

编辑 - 188Pay

188Pay USDT/TRX 支付配置
异步回调地址: http://你的域名/product/notify/?paymethod=epay188
同步跳转地址: http://你的域名/query/auto/{订单号}.html

支付渠道

188Pay USDT

显示名称

USDT(TRC20)

前台展示给买家的名称

商户ID

620f22b6-56a8-4ac8-a5ff-a2...

188Pay后台的商户ID (pid)

商户密钥

ucm3ICWVQvCsxCxxUxAen...

188Pay后台的Secret Key

网关地址

https://api2.188pay.top

如 https://api2.188pay.top

币种

收款币种

是否激活

激活

取消

超时(秒)

600

订单超时时间(秒), 建议600

确认修改

① 商户 ID

填入 188pay 的商户ID (pid)，从 API密钥页面复制

② 商户密钥

填入 188pay 的Secret Key 密钥，从 API密钥页面复制

③ 网关地址

填入https://api2.188pay.top

✅

填写完毕后点击「确认修改」，确保「是否激活」选择了「激活」。用户下单时即可看到 USDT 支付选项。如遇问题请联系 @token188 获取帮助。

第四步

测试支付创建测试商品，验证完整流程

创建测试商品

在 ZFAKA 后台「商品管理」创建一个测试商品，价格设为 0.10

前台下单，选择 USDT 支付

下单后页面应 跳转到 188Pay 收银台，显示钱包地址和待付金额

完成链上转账

向收银台显示的地址转入对应金额的 USDT

ZFAKA 自动发卡

支付成功后 188Pay 回调 ZFAKA，自动完成发卡，可在「订单管理」查看状态

🎉

如果测试商品能成功完成支付并自动发卡，说明配置完全正确！现在可以添加正式商品开始收款了。

参数速查

商户 ID（pid）

从 188pay 商户中心复制

商户密钥（Secret Key）

从 188pay 商户中心复制

网关地址

https://api2.188pay.top

币种

USDT (TRC20) 或 TRX

超时时间

600 秒（10 分钟）

插件标识 — 加密货币通道

epay188

插件标识 — 法币通道（支付宝等）

epay188alipay

支付类型（configure4）— 每条记录独立配置

usdt USDT TRC20 trx TRX alipay 支付宝（法币） wechat 微信支付（法币）

weburl（站点地址） — 务必正确配置，影响回调

正确 http://example.com:8080 （末尾无斜杠）

错误 http://example.com:8080/ （多了 / 会导致回调 404）

常见问题

❓ 安装后在支付设置里看不到 188Pay？

请确认已执行一键安装脚本（install_188pay.php），或手动执行 install.sql。这会在 t_payment 表插入一条记录。如果使用 Docker，确保在 ZFAKA 的容器内操作。

❓ 点击支付后跳转 404？

检查后台支付设置中的「网关地址」是否已填写（如 https://api2.188pay.top）。如果为空，跳转 URL 会指向 ZFAKA 自身而非 188Pay。

❓ 回调失败（支付成功但未自动发卡）？

1. 确认「设置中心 → 配置中心」的 weburl 配置正确，且末尾不要带 /
2. 确认回调地址 http://你的域名/product/notify/?paymethod=epay188 能从外网访问
3. 查看 ZFAKA 日志：log/yewu/ 目录下的日志文件

❓ 如何同时支持 USDT 和 TRX？

在数据库中再插入一条 t_payment 记录，将 configure4 字段改为 trx（默认是 usdt），支付名称改为 TRX 相关名称即可。

❓ 点击支付宝按钮没有反应，或后台编辑页直接 500？

最常见原因：alias（插件别名）里含有下划线。Yaf 框架会把类名里的 _ 当成目录分隔符，导致找不到插件文件报 500。
检查 ZFAKA PHP 日志 log/php/{当天日期}.log，如果看到类似：
Yaf\Loader::autoload(): Failed opening script application/library/Pay/epay188/alipay/... 就是 alias 含下划线（如 epay188_alipay）导致的。删掉下划线，改为 epay188alipay，再清除缓存文件 temp/payment.json 即可。

❓ 后台编辑页看不到「网关地址」「支付类型」字段？

ZFAKA 支持自定义 ADMIN_DIR（安装时可修改，默认是 Goadmin）。后台编辑页的字段来自 application/modules/{ADMIN_DIR}/views/payment/tpl/epay188.html，如果你的 ADMIN_DIR 不是 Goadmin，就需要把模板复制过去：

cp application/modules/Goadmin/views/payment/tpl/epay188*.html \
   application/modules/{你的ADMIN_DIR}/views/payment/tpl/
rm -f temp/payment.json

ADMIN_DIR 的值可以在 application/init.php 里查看。一键安装脚本会自动处理这个问题。

❓ install_188pay.php 访问是 404？

部分 nginx 配置（如宝塔面板默认模板）会把所有请求重写到 ZFAKA 的 index.php，导致浏览器访问脚本返回 404。改用命令行直接执行即可绕过 nginx：
php install_188pay.php 宝塔面板用户可在「网站」→「终端」里执行。

错误排查

! 常见错误排查：

• 网关地址为空：必须填写 https://api2.188pay.top，否则点击支付会 404（跳到 ZFAKA 自身而非 188Pay）。
• 回调地址 404：weburl 末尾带了 / 会导致回调 URL 出现双斜杠 //product/notify/，去掉尾部斜杠即可。
• 签名错误：请检查商户 ID 和商户密钥是否复制完整，粘贴时不要包含多余的空格或换行符。
• 插件文件未生效：确认 application/library/Pay/epay188/epay188.php 文件存在且权限正确（755），否则 ZFAKA 找不到支付类。
• 支付成功但订单未完成：检查 notify_url 是否可被公网访问。本地 localhost 无法收到回调，需部署到公网。
• 支付按钮点击无反应 / 后台编辑页 500：alias 含有下划线，Yaf 自动加载器把 _ 当目录分隔符解析。检查 log/php/{今天}.log，修复方法：把 alias 改为不含下划线的形式（epay188alipay），并删除缓存 temp/payment.json。
• 修改了数据库配置但前台/后台没变化：ZFAKA 把支付配置缓存在 temp/payment.json（TTL 600 秒）。改完数据库后需手动删除该文件强制刷新：rm -f temp/payment.json。

仍无法解决？联系 Telegram @token188 获取支持

188Pay ZFAKA 发卡 接入指南

开始前准备

参数速查

常见问题

错误排查

188Pay ZFAKA 发卡接入指南