← 全部接入指南
选择正确的安装包与 PHP 环境
| 商城平台 | 本安装包的 PHP 环境 |
|---|
| Sylius >=2.0.0 <2.1.0，搭配 PayumBundle 2.6+ / 兼容 Payum 1.7 的核心 | PHP 8.2.x / 8.3.x / 8.4.x（同时满足商城依赖锁文件的要求） |
|---|
使用安装包与确切商城核心均允许的 PHP 版本，插件不能使旧商城核心兼容新版 PHP。
新包使用可选 request_id 去重功能，需要 MochiPay Web65 或更高版本。已有客户可继续使用当前插件和 API 接入。
01 · 准备 MochiPay 账户
- 创建账户 · 启用订阅.
- 钱包 · 为准备提供的每种币种和网络启用收款钱包，并在结账前备份恢复资料。
- API 凭证 · 商户 API Key 和 Secret 仅保存在服务端，不能放入结账 HTML 或浏览器脚本。
02 · 安装并启用原生网关
- 将 MochiPaySylius 解压到 plugins/MochiPaySylius。添加本地 Composer path 仓库并运行 composer require mochipay/sylius-plugin:1.0.0。
- 在 config/bundles.php 注册 MochiPay\Sylius\MochiPayBundle，并按 ZIP 内 README.md 导入路由。
- 运行 bin/console cache:clear 和 bin/console mochipay:install，已有支付尝试记录会保留。
- 使用 MochiPay 网关工厂创建原生支付方式。填写凭据、启用 MochiPay 和原生支付方式，并分配销售渠道。
- 使用 Sylius 2.0 的 Payum 结账。支持 MySQL/MariaDB 和 PostgreSQL；Sylius 1.x 和 2.1 及以上需要不同的适配器。
每个 ZIP 内的英文 README 包含准确路径、原生配置、依赖和升级说明，请按对应平台的文件操作。
04 · ON_SITE 和 HPP 使用同一笔支付
ON_SITE商城内支付弹窗
默认 ON_SITE 弹窗在商城域名下展示准确金额、收款地址、网络、二维码和支付状态。
HPPMochiPay 托管支付页
HPP 打开 MochiPay 的 payment_url，结账后返回商城。可在同一网关设置中选择 HPP。
重新打开结账或切换展示模式会复用已保存的支付订单。MochiPay API 无需新增 payment_mode 参数。
体验公开 ON_SITE/HPP 模拟演示 →
05 · 正式使用前验证测试订单
- 创建小额测试订单。付款前确认法币总额、所选币种、网络及准确加密货币金额。
- 确认服务端查询 MochiPay，只有匹配的 PAID 结果才更新原生已付款状态。返回 URL 或回调内容本身不能证明付款。
- 测试 HPP、ON_SITE、重新打开结账及重复通知，确认复用同一订单且只处理一次支付完成。
这些下载包已完成源码与接口检查及模拟结账验证。完整原生商城安装和真实付款结账仍需测试环境验收。
了解服务端付款验证 →
排查问题与下载
若网关未显示，请检查准确商城分支、PHP、缓存、原生支付方式启用状态及渠道限制。若订单一直等待付款，请检查凭据、有效订阅、钱包和公开回调可达性。升级时保留已有支付尝试记录。