PAYUNi 超商代碼金流 for WooCommerce

整合 PAYUNi 超商代碼付款功能到 WooCommerce，支援 7-ELEVEN、全家、萊爾富、OK 超商代碼繳費。

功能特色

• ✅ 完整支援 PAYUNi 超商代碼 API
• ✅ AES-256-GCM 加密傳輸
• ✅ 自動產生超商繳費代碼
• ✅ 訂單頁面顯示繳費資訊
• ✅ Email 通知包含繳費代碼
• ✅ 付款完成自動更新訂單狀態為「處理中」
• ✅ 支援測試環境與正式環境切換
• ✅ 完整的後台設定介面
• ✅ 詳細的交易日誌記錄

系統需求

• WordPress 5.8 或更高版本
• WooCommerce 5.0 或更高版本
• PHP 7.4 或更高版本
• PHP OpenSSL 擴展

安裝方式

方法一：上傳安裝

1. 將整個 payuni-cvs-for-woocommerce 資料夾上傳到 /wp-content/plugins/ 目錄
2. 在 WordPress 管理後台的「插件」選單中啟用「PAYUNi 超商代碼金流 for WooCommerce」
3. 前往 WooCommerce > 設定 > 付款 > PAYUNi 超商代碼 進行設定

方法二：FTP 上傳

1. 解壓縮下載的壓縮檔
2. 透過 FTP 將 payuni-cvs-for-woocommerce 資料夾上傳到 /wp-content/plugins/ 目錄
3. 在 WordPress 管理後台啟用插件
4. 進行金流設定

設定步驟

1. 取得 PAYUNi 金流資訊

首先，您需要從 PAYUNi 平台取得以下資訊：

• 商店代號 (MerID)
• HashKey
• HashIV

2. 設定插件

前往 WooCommerce > 設定 > 付款 > PAYUNi 超商代碼，填寫以下資訊：

基本設定

• 啟用/停用：勾選以啟用此付款方式
• 標題：顧客在結帳時看到的付款方式名稱（預設：超商代碼付款）
• 描述：顧客在結帳時看到的付款方式描述

測試模式

• 測試模式：在測試階段請勾選，正式上線後取消勾選
  • 測試環境：https://sandbox-api.payuni.com.tw/api/cvs
  • 正式環境：https://api.payuni.com.tw/api/cvs

PAYUNi 金流資訊

• 商店代號 (MerID)：輸入您的 PAYUNi 商店代號
• HashKey：輸入您的 HashKey
• HashIV：輸入您的 HashIV

進階設定

• 付款通知網址 (NotifyURL)：PAYUNi 付款完成後的回調網址

  • 預設值：https://您的網域/?payuni_cvs_notify=callback
  • 此網址需要設定在 PAYUNi 後台

• 繳費期限（天數）：超商代碼的有效期限（1-7天，預設 3 天）

3. 在 PAYUNi 後台設定 NotifyURL

登入 PAYUNi 商店後台，將以下網址設定為付款通知網址：

https://您的網域/?payuni_cvs_notify=callback

使用流程

顧客端流程

1. 選擇付款方式：顧客在結帳頁面選擇「超商代碼付款」
2. 送出訂單：系統自動向 PAYUNi 申請超商代碼
3. 取得繳費資訊：
   • 在訂單確認頁面顯示超商名稱、繳費代碼、繳費期限
   • 收到包含繳費資訊的訂單確認 Email
4. 完成繳費：顧客於繳費期限內，前往指定超商出示代碼完成付款
5. 訂單完成：付款完成後，系統自動將訂單狀態更新為「處理中」

管理員流程

1. 查看訂單：在後台訂單列表可以看到訂單狀態
2. 檢視繳費資訊：點擊訂單可以查看：
   • 超商名稱
   • 繳費代碼
   • 繳費期限
   • 交易編號
   • 付款狀態
3. 追蹤訂單狀態：
   • 待付款：顧客尚未完成付款
   • 處理中：顧客已完成付款，等待出貨

訂單狀態說明

• 待付款 (On Hold)：已產生超商代碼，等待顧客繳費
• 處理中 (Processing)：顧客已完成付款，訂單進入處理流程
• 已完成 (Completed)：訂單已完成出貨

測試流程

使用測試環境

1. 勾選「測試模式」
2. 使用測試環境的 MerID、HashKey、HashIV
3. 進行測試訂單
4. 系統會產生測試用的超商代碼
5. 在 PAYUNi 測試後台可以模擬付款完成

切換到正式環境

1. 取消勾選「測試模式」
2. 更換為正式環境的 MerID、HashKey、HashIV
3. 確認 NotifyURL 已在 PAYUNi 正式後台設定
4. 進行小額真實交易測試
5. 確認付款流程正常後開放使用

常見問題 (FAQ)

Q1: 為什麼訂單狀態沒有自動更新？

A: 請檢查以下項目：

• NotifyURL 是否正確設定在 PAYUNi 後台
• NotifyURL 是否可以從外部訪問（不要有防火牆阻擋）
• 檢查 WooCommerce > 狀態 > 日誌，查看是否有錯誤訊息

Q2: 如何查看交易日誌？

A:

1. 確保已啟用 WordPress 的 WP_DEBUG 模式
2. 前往 WooCommerce > 狀態 > 日誌
3. 查看 payuni-cvs-{日期}.log 檔案

Q3: 超商代碼沒有顯示在訂單頁面？

A: 請確認：

• 訂單使用的付款方式是「PAYUNi 超商代碼」
• 訂單狀態為「待付款」或「處理中」
• PAYUNi API 回應成功（檢查日誌）

Q4: 如何設定 WP_DEBUG？

A: 編輯 wp-config.php 檔案，加入或修改：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Q5: NotifyURL 的預設值是什麼？

A: 預設的 NotifyURL 格式為：

https://您的網域/?payuni_cvs_notify=callback

您可以在插件設定中自訂此網址。

檔案結構

payuni-cvs-for-woocommerce/
├── payuni-cvs-for-woocommerce.php    # 主插件檔案
├── includes/
│   ├── class-payuni-cvs-crypto.php          # 加解密工具類別
│   ├── class-wc-gateway-payuni-cvs.php      # WooCommerce 金流閘道
│   └── class-payuni-cvs-notify-handler.php  # 付款通知處理
└── README.md                                 # 說明文件

安全性說明

• 使用 AES-256-GCM 加密演算法
• 所有資料傳輸都經過加密
• SHA256 雜湊驗證確保資料完整性
• 敏感資料儲存在 WordPress 資料庫中

技術支援

如有任何問題，請聯繫：

• PAYUNi 官方網站：https://www.payuni.com.tw
• PAYUNi 客服信箱：service@payuni.com.tw

版本歷程

1.0.0 (2025-11-01)

• 首次發布
• 支援 PAYUNi 超商代碼付款
• 完整的訂單狀態管理
• 自動付款通知處理

授權

本插件遵循 GPL v2 或更新版本授權。

開發者資訊

Hook 支援

插件提供以下 WordPress Hooks 供開發者使用：

// 在付款成功後執行自訂動作
add_action('woocommerce_payment_complete', function($order_id) {
    $order = wc_get_order($order_id);
    if ($order->get_payment_method() === 'payuni_cvs') {
        // 您的自訂程式碼
    }
});

過濾器

// 自訂商品描述
add_filter('woocommerce_payuni_cvs_product_description', function($description, $order) {
    return '您的自訂描述';
}, 10, 2);

注意事項

1. 請確保您的網站使用 HTTPS 連線
2. 請定期備份您的網站資料
3. 測試完成後記得切換到正式環境
4. 保管好您的 HashKey 和 HashIV，不要公開分享
5. 建議在正式環境上線前，進行完整的測試流程

感謝使用 PAYUNi 超商代碼金流 for WooCommerce！