WooCommerce 外掛

應援的 WooCommerce 外掛會在結帳時把消費者導到應援的結帳頁付款，付款完成後自動更新 WooCommerce 訂單狀態。

• 付款方式：信用卡、超商繳費
• 原始碼與下載：github.com/OEN-Tech/woocommerce-oen-payment
• 網站需求：PHP 8.1 以上、WordPress 6.1 以上、WooCommerce 8.2 以上

開始前

1. 金流已開通。 見開通金流與付款方式。
2. 請應援開通「OenPay Embed」。 外掛使用的金鑰要在這個分頁產生。開通後，CRM「總設定」會出現「OenPay Embed」分頁。
3. 要收超商繳費的話，請應援開通超商代碼。 申請表上沒有這個選項。

外掛不需要開啟 API 串接（開發者模式）。

1. 取得 Secret Key

1. 進入 CRM「總設定」→「OenPay Embed」分頁，找到「Embed API Key」。
2. 按「產生金鑰」。這是高風險操作，要輸入你的網域名稱才能確認。
3. 畫面會顯示 Publishable Key 與 Secret Key。複製 Secret Key（sk_ 開頭），先存在安全的地方。
4. 勾選「我已妥善保存 Secret Key」，按「立即清除」。

Secret Key 只會顯示一次

• 關閉後就看不到完整的 Secret Key，畫面 5 分鐘後也會自動清除。忘記複製的話，只能重新產生。
• 外掛要的是這把 Secret Key，不是「開發者」分頁的「存取 Token」。
• 正式環境後台產生的金鑰就是正式收款用的。外掛的測試模式要用測試環境後台產生的金鑰，測試環境帳號請聯絡應援。
• 同一分頁的「允許的 returnUrl 網域」是給 Embed 用的，只用 WooCommerce 外掛不需要填。

2. 安裝外掛

1. 從 GitHub 的 Releases 頁下載最新版本的原始碼壓縮檔並解壓縮。
2. 把資料夾上傳到網站的 /wp-content/plugins/。
3. 在 WordPress 後台「外掛」頁面啟用「WooCommerce OEN 金流付款」。

3. 設定外掛

到「WooCommerce」→「設定」→「OEN」：

設定項目	填什麼
啟用 OEN 金流付款方式	勾選。這是總開關
訂單編號前綴	選填。加在 WooCommerce 訂單編號前面
顯示訂單商品名稱	選填。開啟後會把每個商品明細傳給應援
在 Email 中顯示付款資訊	選填。在訂單通知信加上金流編號、繳費代碼等資訊
OEN 測試環境	測試時勾選；正式上線前要取消
商店代碼	你的網域名稱。例如應援頁是 ming.oen.tw，就填 ming
Secret Key	貼上第 1 步的 Secret Key
Webhook Secret	留空

按「儲存變更」。外掛會自動向應援登記付款通知網址（https://你的網站/?wc-api=oen_payment），並把簽章密鑰自動填進「Webhook Secret」。

不用到 CRM 設定 webhook

外掛說明文件寫「至 OEN CRM 後台設定 Webhook 網址」，這一步不需要做。CRM「OenPay Embed」分頁新增的 webhook 收不到外掛需要的付款事件，外掛存檔時會自己完成登記。

如果「Webhook Secret」已經手動填過，外掛就不會自動登記。這時請勾選「Re-register webhook」再存一次。

4. 啟用付款方式

到「WooCommerce」→「設定」→「付款方式」，啟用「OEN 信用卡」與（或）「OEN 超商繳費」。

5. 測試後上線

1. 在測試模式下，用信用卡下一筆訂單，確認付款後 WooCommerce 訂單狀態會自動更新。
2. 換成正式環境後台產生的 Secret Key，取消勾選「OEN 測試環境」。
3. 勾選「Re-register webhook」後儲存，讓外掛重新登記正式環境的付款通知。
4. 用正式環境下一筆小額訂單確認，再從 WooCommerce 退款。

切換環境或網站網址之後，都要勾選「Re-register webhook」再存一次。

退款

付款方式	怎麼退	WooCommerce 會自動更新嗎
信用卡	在 WooCommerce 訂單頁退款	會
超商繳費	在 CRM 金流明細退款，要填消費者的退款帳戶，見退款	不會，請手動更新訂單

信用卡訂單請從 WooCommerce 退款。從 CRM 退款時，WooCommerce 訂單不一定會自動變成已退款。

發票

開通「應援代開電子發票」後，付款完成時會自動開立電子發票，支援手機條碼、自然人憑證、統編與捐贈。見電子發票。

常見問題

找不到「OenPay Embed」分頁？ 請應援開通 OenPay Embed，並確認你的帳號有 API 串接設定的權限。

儲存時沒有自動填入 Webhook Secret？ 確認已勾選「啟用 OEN 金流付款方式」，並填好商店代碼與 Secret Key，再勾選「Re-register webhook」儲存一次。成功時會顯示英文訊息「OEN webhook registered」。

付款成功了，WooCommerce 訂單卻沒有更新？ 先確認網站可以從外部以 https 連線，以及 Webhook Secret 已經自動填入。仍有問題請聯絡客服，並提供網域名稱與訂單編號。

WooCommerce 的交易在 CRM 哪裡看？ 在「金流管理」→「金流列表」，類型是「現金購買」。