← 全部接入指南
選擇正確的安裝包與 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、快取、原生支付方式啟用狀態及渠道限制。若訂單一直等待付款，請檢查憑據、有效訂閱、錢包和公開回撥可達性。升級時保留已有支付嘗試記錄。