技術文件目前產品線：WooCommerce 商店

WooCommerce 串接 PAYUNi：RY Tools 設定與上線檢查

更新日期
閱讀時間
約 7 分鐘
來源狀態
draft

本篇說明

本篇說明如何用 RY Tools for WooCommerce 串接 PAYUNi、設定 MerID 與金鑰、確認 Checkout 類型、完成 Sandbox 測試並安全切換正式收款。

適合誰使用

負責設定 WooCommerce 金流的網站管理員或 Digital By Arden 專案執行者

開始前準備

  • PAYUNi 商店與準備使用的支付方式已通過審核
  • 先確認結帳頁使用 WooCommerce Checkout Block 或傳統 [woocommerce_checkout] shortcode
  • 建立可測試的 staging 或 LocalWP 環境，並確認 WordPress、WooCommerce 與 PHP 符合 RY Tools 最低版本
  • 準備 PAYUNi 測試商店的 MerID、Hash Key 與 Hash IV，但不要把金鑰貼進公開工單或截圖

教學內容

先確認外掛與 Checkout 路線

本篇採用 Digital By Arden 目前驗證中的 RY Tools for WooCommerce 路線；如果網站已經使用 PAYUNi 官方外掛或其他 PAYUNi 外掛，先停止並確認遷移方式，不要把兩套設定混在同一個結帳流程。

RY Tools 免費版在預設 Block Checkout 時會提示需要 Pro；免費版應使用傳統 shortcode checkout，或先完成 Pro 的實際相容性測試。

RY Tools 使用 WooCommerce 訂單物件操作，但上線前仍要在目標網站驗證 HPOS、Checkout 與訂單狀態，不要只依賴程式存在就宣告相容。

  1. 前往 外掛 > 安裝外掛，安裝並啟用 RY Tools for WooCommerce。
  2. 確認目標環境至少符合 WordPress 6.8、WooCommerce 9.0 與 PHP 8.2。
  3. 檢查結帳頁；若使用 RY 免費版，將 Block Checkout 改為傳統 [woocommerce_checkout] shortcode，或先驗證 Pro。

取得 PAYUNi 商店串接資訊

PAYUNi 串接前要先建立收款商店並取得 MerID，再從商店串接資訊取得 Hash Key 與 Hash IV。

ReturnURL 是顧客瀏覽器返回頁面，實際交易結果應以 NotifyURL 通知為主；不能只看到付款完成頁就把訂單當成已付款。

  1. 登入 PAYUNi 平台，從商店串接資訊取得商店代號 MerID、Hash Key 與 Hash IV。
    2. PAYUNi 官方手冊中的商店代號、Hash Key、IV Key 與 NotifyURL、ReturnURL 串接設定
    PAYUNi 官方會員手冊：商店串接資訊與 API URL 設定示意。
  2. 確認目前取得的是 Sandbox 測試商店憑證，不要先使用正式金鑰。
  3. 不要在文章、聊天群組或未遮蔽截圖中保存 MerID、Hash Key 與 Hash IV。

設定 RY Tools 的 PAYUNi 金鑰

RY Tools 的 PAYUNi 全域設定包含 Sandbox、MerID、HashKey、HashIV、交易編號前綴與付款品項名稱。

  1. 前往 WooCommerce > 設定 > RY Tools > PAYUNi gateway options。
  2. 開啟 Sandbox，填入測試商店的 MerID、HashKey 與 HashIV。
  3. 如需交易編號前綴，只使用最多三個英文字母或數字；沒有需求可留空。
  4. 儲存設定後，不要把含有金鑰的後台畫面截圖傳到公開管道。

啟用需要的付款方式

RY Tools 目前提供 PAYUNi 信用卡、信用卡分期、ATM 與超商代碼；實際可啟用項目仍受 PAYUNi 商店審核結果限制。

  1. 前往 WooCommerce > 設定 > 付款。
  2. 只啟用 PAYUNi 已核准且商店確實要提供的付款方式。
  3. 依付款方式設定前台名稱、說明、金額限制；ATM 與超商代碼另確認繳費期限。
  4. 到前台結帳頁確認每個付款方式只出現一次，且名稱與說明符合商店需求。

完成 Sandbox 上線測試

PAYUNi 的測試與正式 UPP 使用不同端點；RY Tools 會依 Sandbox 設定切換端點。

以下是依實際啟用付款方式調整的建議 UAT 矩陣，不是 PAYUNi 官方宣告的固定最低清單。

  1. 建立一筆成功付款，確認回到商店後訂單、交易編號與訂單備註正確。
  2. 測試付款失敗或中斷，確認訂單不會被誤標成已付款。
  3. 若啟用 ATM 或超商代碼，測試待付款、付款通知與逾期流程。
  4. 確認 NotifyURL 通知可從公開 HTTPS 網址到達網站，訂單狀態不只依賴 ReturnURL。
  5. 依已啟用的付款方式測試退款或取消，並核對 PAYUNi 後台與 WooCommerce 訂單備註。

切換正式環境

只有 Sandbox 測試、付款通知與訂單狀態都通過後，才可改用正式商店憑證並關閉 Sandbox。

PAYUNi Period 續期收款使用獨立 API；一般 UPP 外掛不能自動視為支援 Woo Subscriptions 自動續扣。

  1. 先記錄 Sandbox 測試結果與已驗證的付款方式。
  2. 在維護時段改填正式商店的 MerID、HashKey 與 HashIV，再關閉 Sandbox。
  3. 用最小金額完成一筆正式交易，核對 PAYUNi 後台、WooCommerce 訂單、NotifyURL 與退款流程。
  4. 若需要定期扣款，先建立獨立的 PAYUNi Period 串接需求，不要直接啟用 Woo Subscriptions 收款。

介面名稱對照

介面名稱 說明
Sandbox 測試模式；RY Tools 會改用 PAYUNi 測試端點與目前填入的測試商店憑證。
MerID PAYUNi 商店代號，用來識別交易要進入哪一個收款商店。
HashKey / HashIV PAYUNi 交易資料加解密與驗證使用的商店串接金鑰。
ReturnURL 付款完成後，顧客瀏覽器返回商店的前景網址。
NotifyURL PAYUNi 從伺服器通知交易結果的網址，訂單狀態應以此通知為主。
Checkout Block WooCommerce 區塊式結帳；RY Tools 免費版預設需要 Pro 才支援。

注意事項

注意

MerID、Hash Key 與 Hash IV 是金流憑證，不可放進公開工單、文章、版本庫或未遮蔽截圖。

注意

ReturnURL 只代表瀏覽器返回；訂單付款結果必須以 NotifyURL 與必要的交易查詢為主。

注意

RY Tools 免費版的 Checkout Block 需要 Pro；不要在未驗證相容性時直接上線。

注意

一般 UPP 不等於 PAYUNi Period 續期收款；訂閱自動續扣必須另案設計與測試。

常見問題

付款頁顯示成功，WooCommerce 訂單卻沒有變成已付款，該看哪裡？

先看訂單備註與付款外掛記錄，再確認 NotifyURL 是否真的送達；必要時用 PAYUNi 交易查詢核對。不要只依賴 ReturnURL 的前景頁面。

RY Tools 免費版可以直接用 WooCommerce Checkout Block 嗎？

目前免費版程式在預設 Block Checkout 時明示需要 RY Tools Pro。若不使用 Pro，請改用傳統 shortcode checkout，並重新測試完整結帳流程。

一般 PAYUNi 串接可以直接拿來做 WooCommerce 訂閱自動扣款嗎？

不能直接假設可以。PAYUNi Period 使用獨立 API 與每期通知，官方 WooCommerce 外掛目前也沒有公開 Period 或 Woo Subscriptions 自動續扣實作，必須另案確認或客製。

什麼時候可以關閉 Sandbox？

成功、失敗、中斷、付款通知、訂單狀態，以及實際啟用付款方式的延遲付款與退款測試都通過後，再換正式憑證並關閉 Sandbox。

官方來源

知識標籤

還是卡住了？

先把問題問清楚，通常比直接開工單更快。複製下面的結構，補上你的情況後送出。

用 AI 先釐清問題

/ai 我正在閱讀「WooCommerce 串接 PAYUNi：RY Tools 設定與上線檢查」，目前卡在：

我已嘗試：

我看到的畫面／錯誤訊息：

請用一步一步的方式告訴我下一步。

需要我們實際進入網站調整設定、修改佈景主題或處理資料時，再建立 /task 工單。