PAYUNi 虛擬帳號 (ATM) 金流 for WooCommerce

整合 PAYUNi ATM 虛擬帳號付款功能到 WooCommerce，支援各大銀行 ATM 轉帳及網路銀行付款。

功能特色

• ✅ 完整支援 PAYUNi ATM 虛擬帳號 API
• ✅ AES-256-GCM 加密傳輸
• ✅ 自動產生虛擬帳號
• ✅ 支援多家銀行（中國信託、玉山、台灣銀行等）
• ✅ 單繳帳號或長期固定帳號
• ✅ 訂單頁面顯示虛擬帳號資訊
• ✅ Email 通知包含轉帳資訊
• ✅ 付款完成自動更新訂單狀態為「處理中」
• ✅ 支援測試環境與正式環境切換
• ✅ 完整的後台設定介面
• ✅ 自訂商品名稱功能
• ✅ 詳細的交易日誌記錄

系統需求

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

安裝方式

方法一：上傳安裝

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

方法二：FTP 上傳

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

設定步驟

1. 取得 PAYUNi 金流資訊

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

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

2. 設定插件

前往 WooCommerce > 設定 > 付款 > PAYUNi 虛擬帳號 (ATM)，填寫以下資訊：

基本設定

• 啟用/停用：勾選以啟用此付款方式
• 標題：顧客在結帳時看到的付款方式名稱（預設：ATM 虛擬帳號轉帳）
• 描述：顧客在結帳時看到的付款方式描述

測試模式

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

PAYUNi 金流資訊

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

ATM 專屬設定

• 收款銀行代碼 (BankType)：選擇虛擬帳號的收款銀行

  • 004 - 台灣銀行
  • 005 - 土地銀行
  • 006 - 合作金庫
  • 007 - 第一銀行
  • 008 - 華南銀行
  • 009 - 彰化銀行
  • 011 - 上海銀行
  • 012 - 台北富邦
  • 013 - 國泰世華
  • 016 - 高雄銀行
  • 017 - 兆豐銀行
  • 050 - 台灣企銀
  • 808 - 玉山銀行
  • 822 - 中國信託（預設）

• 繳費帳號類型 (PaySet)：

  • 單繳帳號（一次性）：每筆訂單產生不同的虛擬帳號（預設，推薦）
  • 長期固定帳號：每位顧客使用相同的虛擬帳號

進階設定

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

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

• 繳費期限（天數）：虛擬帳號的有效期限（1-60天，預設 3 天）

• 自訂商品名稱：在 PAYUNi 顯示的商品名稱

  • 若留空，將使用購物車內的商品名稱
  • 例如：線上商城購物

3. 在 PAYUNi 後台設定 NotifyURL

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

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

使用流程

顧客端流程

1. 選擇付款方式：顧客在結帳頁面選擇「ATM 虛擬帳號轉帳」
2. 送出訂單：系統自動向 PAYUNi 申請虛擬帳號
3. 取得轉帳資訊：
   • 在訂單確認頁面顯示銀行代碼、虛擬帳號、轉帳金額、繳費期限
   • 收到包含轉帳資訊的訂單確認 Email
4. 完成轉帳：顧客於繳費期限內，使用 ATM 或網路銀行轉帳
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:

• 單繳帳號必須轉帳「完全相同」的金額
• 金額不符將無法自動對帳
• 建議在訂單頁面明確標示「請勿多轉或少轉」
• 如有金額不符，需聯繫 PAYUNi 客服手動處理

Q3: 如何查看交易日誌？

A:

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

Q4: 虛擬帳號沒有顯示在訂單頁面？

A: 請確認：

• 訂單使用的付款方式是「PAYUNi 虛擬帳號 (ATM)」
• 訂單狀態為「待付款」或「處理中」
• PAYUNi API 回應成功（檢查日誌）

Q5: 如何設定 WP_DEBUG？

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

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

Q6: 單繳帳號和長期固定帳號的差異？

A:

• 單繳帳號：每筆訂單一個新帳號，付款後失效，適合一般電商
• 長期固定帳號：每位顧客固定帳號，可重複使用，適合會員制

建議一般電商使用「單繳帳號」。

Q7: 支援哪些銀行？

A: 目前支援的銀行包括：

• 中國信託（預設）
• 玉山銀行
• 台灣銀行
• 第一銀行
• 華南銀行
• 國泰世華
• 台北富邦
• 等多家銀行

具體可用的銀行請洽 PAYUNi 客服確認。

檔案結構

payuni-atm-for-woocommerce/
├── payuni-atm-for-woocommerce.php    # 主插件檔案
├── includes/
│   ├── class-payuni-atm-crypto.php          # 加解密工具類別
│   ├── class-wc-gateway-payuni-atm.php      # WooCommerce 金流閘道
│   └── class-payuni-atm-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 ATM 虛擬帳號付款
• 完整的訂單狀態管理
• 自動付款通知處理
• 支援多家銀行選擇
• 自訂商品名稱功能

授權

本插件遵循 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_atm') {
        // 您的自訂程式碼
    }
});

過濾器

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

注意事項

1. 金額精確度：使用單繳帳號時，轉帳金額必須完全相符
2. HTTPS 連線：請確保您的網站使用 HTTPS 連線
3. 定期備份：請定期備份您的網站資料
4. 測試完成：測試完成後記得切換到正式環境
5. 金鑰保管：保管好您的 HashKey 和 HashIV，不要公開分享
6. 完整測試：建議在正式環境上線前，進行完整的測試流程
7. 顧客說明：建議在訂單頁面提醒顧客「請勿多轉或少轉」

與超商代碼的差異

本插件是 ATM 虛擬帳號版本，與超商代碼版本的主要差異：

建議同時安裝兩個插件，提供顧客更多付款選擇。

感謝使用 PAYUNi 虛擬帳號 (ATM) 金流 for WooCommerce！