Drupal Commerce 介紹與綠界 ECPay 金流串接實戰
Drupal Commerce 是什麼?
Drupal Commerce 是建構在 Drupal 上的開源電子商務模組，可以設計商品頁面、並提供訂單、結帳串接API實現自主的金流（不會被平台抽成），也能和原本的網站內容、會員、權限、Views 無縫結合。它由 Centarro 主導維護，目前主力版本為Commerce 3.x，支援 Drupal 10.3 以上與 Drupal 11。
它的定位並非「開箱即用的商店」，而是「可組裝的電商框架」，很適合需要客製流程、內容與商品深度整合、或與既有系統（ERP、會員系統）串接的專案。 我們把Drupal Commerce跟其他大家熟悉的平台做比較，就可以發現它除了可以用在一般電商之外，它更適合定位在B2B的商務市場。
| 平台 | 類型 | 適合情境 | 客製彈性 |
|---|---|---|---|
| Drupal Commerce | 開源框架（自架） | 內容導向電商、複雜商品/流程、B2B | 很高 |
| WooCommerce | WordPress 外掛（自架） | 中小型商店、快速上線 | 中 |
| Shopify | SaaS | 標準零售、不想管主機 | 低到中 |
| SHOPLINE / 91APP | 台灣在地 SaaS | 在地金物流整合、行銷工具 | 低 |
對已經以 Drupal 經營網站的客戶而言，Commerce 最大的價值是不需要另建一套商店系統，會員、內容與訂單都在同一個後台。
核心架構
Drupal Commerce 由幾個各司其職的子模組組成，理解它們的分工，就能看懂金流要接在哪裡。
| 模組 | 負責什麼 | 串金流時的關聯 |
|---|---|---|
| Store（commerce_store） | 商店本身：幣別、稅制、地址 | 幣別需設為 TWD |
| Product（commerce_product） | 商品與變體（Variation）：SKU、價格、屬性 | 商品名稱會帶入綠界 ItemName |
| Order（commerce_order） | 訂單、訂單項目、狀態流程（Workflow） | 付款成功後訂單轉為 completed |
| Cart（commerce_cart） | 購物車，實際上是 draft 狀態的訂單 | — |
| Checkout（commerce_checkout） | 結帳流程與各個結帳窗格（Pane） | 「付款」步驟會導向綠界 |
| Payment（commerce_payment） | 金流閘道（Gateway）、付款紀錄、退款 | 綠界模組就是一個 Gateway 外掛 |
| Price / Promotion / Tax | 價格計算、促銷、稅金 | 金額需為整數新台幣 |
| Shipping（contrib） | 運送方式與運費 | 超商取貨另需物流串接 |
Payment 模組把金流閘道分成兩類，這是串接設計的關鍵：
- On-site（站內）：信用卡資料在自己的結帳頁輸入，再透過 API 或 Token 送到金流商，例如 Stripe。網站需處理更多 PCI DSS 責任。
- Off-site（站外導向）：結帳時把消費者導到金流商的付款頁，付完再導回網站，卡號從不經過我方伺服器。綠界 全方位金流（AIO）就是這一類，在 Commerce 裡對應 OffsitePaymentGatewayBase。
Off-site 閘道有三個重要的回呼點：onReturn() 處理消費者瀏覽器導回、onCancel() 處理取消、onNotify() 處理金流商伺服器端的背景通知（Webhook）。後面的串接流程，基本上就是把綠界的規格對應到這三個方法。
為什麼要串接綠界 ECPay
在台灣第三方支付平台，有綠界科技、藍新金流..提供代收代付的服務。本文僅以綠界為例，你也可以使用藍新金流。綠界一次串接就能取得信用卡、ATM 虛擬帳號、超商代碼等在地付款方式。另外，Drupal Commerce 官方生態以國外的 Stripe、PayPal、Braintree為主，這些跨境的金流，在台灣境內的交易不能使用，必須使用政府核可的金流公司才可以交易。
綠界「全方位金流（All-In-One, AIO）」的付款方式大致如下：
| 付款方式 | ChoosePayment 值 | 付款結果何時確定 | 對訂單流程的影響 |
|---|---|---|---|
| 信用卡（含分期、定期定額） | Credit | 當下授權 | 即時完成，最容易處理 |
| ATM 虛擬帳號 | ATM | 消費者日後轉帳 | 先取號、後入帳，訂單需「待付款」狀態 |
| 超商代碼 | CVS | 消費者到超商繳費 | 同 ATM，有繳費期限 |
| 超商條碼 | BARCODE | 消費者到超商繳費 | 同 ATM |
| 網路 ATM | WebATM | 當下完成 | 需讀卡機，使用率低 |
| 全部由消費者選 | ALL | 依所選方式 | 最常用的設定 |
從架構角度看，最需要注意的是 ATM 與超商這類「非即時」付款：消費者從綠界導回網站時只拿到繳費帳號或代碼，錢還沒到。真正的入帳結果可能幾小時或幾天後才透過背景通知送達，所以訂單狀態絕不能只靠瀏覽器導回來判斷。
此外，綠界另有電子發票與物流（超商取貨）API，是和金流分開的串接。本文只處理金流。
串接前準備
1. 取得三組金鑰
綠界以 MerchantID（特店編號）、HashKey、HashIV 三個值識別商店並產生檢查碼。開發階段使用綠界開發者文件提供的公開測試帳號即可（例如常見的測試特店 3002607，實際數值請以官方最新文件為準）；正式上線前需申請特店、完成審核，再到廠商後台取得正式金鑰。正式金鑰不應寫進版控，建議放在 settings.php 的 config override 或環境變數。
2. 區分兩個環境
| 環境 | 付款頁網址 | 用途 |
|---|---|---|
| 測試(test) | payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5 | 開發與驗收，不會真的扣款 |
| 正式(live) | payment.ecpay.com.tw/Cashier/AioCheckOut/V5 | 上線後使用 |
在 Commerce 裡，這對應到金流閘道設定中的 Mode（test / live），切換模式時金鑰也要一併更換。
3. 主機環境需求
- 綠界得能連到你的網站：付款結果是由綠界伺服器主動 POST 到 ReturnURL，localhost 或只在內網的開發機收不到。本機開發可用 cloudflared 等通道工具，或直接在有公開網址的測試站上開發。
- HTTPS 與標準埠號：使用有效憑證（Let's Encrypt 即可），回呼網址走 80/443。
- 防火牆與 WAF：若前端有 FortiGate、Cloudflare 或 ModSecurity，要確認不會擋下綠界的 POST。通知被擋是「付了錢但訂單沒更新」最常見的原因。
- 時區與時間同步：MerchantTradeDate 以台灣時間（Asia/Taipei）計算，確認 PHP 與系統時區一致、NTP 正常。
- 程式層：Drupal 10.3+ / 11、Commerce 3.x（或 2.x）、PHP 8.1+，以 Composer 管理模組。
4. 商店基本設定
Store 幣別設為 TWD，並確認價格、運費、促銷計算後的總額為整數。綠界的 TotalAmount 只接受整數，小數點會直接導致交易失敗。
串接步驟
整個串接可以拆成七個步驟：安裝模組、建立閘道、調整結帳流程、組付款參數、計算檢查碼、處理背景通知、處理瀏覽器導回。前三步是設定，後四步是模組內部在做的事，理解它們才能在出問題時快速排錯。
綠界 AIO 付款流程 · 7 個步驟
消費者的瀏覽器在 Drupal 與綠界之間來回兩趨，但訂單是否已付款，只由步驟 4 的伺服器背景通知決定。
步驟一：安裝模組
特別感謝 Jiajun Xu 為Drupal 11開發ECpay 模組
Commerce_ecpay_allinone Gitlab網址
由於packages.drupal.org 目前只有 1.x-dev，還沒收錄 2.0.x 分支。要讓 Composer 直接從 drupalcode 的 Git 抓取，須先編輯網站根目錄內的composer.json的repositories區塊中，把 drupalcode 的 Git 來源加在 packages.drupal.org前面，如下圖
接著安裝commerce_ecpay_allinone
然後到後台把ECpay模組安裝好。最後再清除快取
步驟二：建立金流閘道
到「Commerce → 設定 → 付款 → 金流閘道」（/admin/commerce/config/payment-gateways）新增閘道，選擇綠界外掛，填寫：
- 模式：Test（開發階段）或 Live
- MerchantID、HashKey、HashIV
- 開放的付款方式（ChoosePayment）、ATM 繳費期限、超商代碼有效時間
- 條件（Conditions）：可限制只有特定商店、幣別或金額範圍才顯示綠界
步驟三：調整結帳流程
到「結帳流程」（/admin/commerce/config/checkout-flows）確認預設流程包含「付款資訊」與「付款處理」兩個窗格。「付款處理」在 Off-site 閘道會產生一個自動送出的表單，把消費者帶到綠界付款頁。另外要決定訂單在「下單但尚未付款」時的狀態，ATM、超商付款特別需要這個中間狀態。
步驟四：增加付款閘道Ecpay並設定付款參數
最後測試購買流程與金流付款成功畫面如下
最後付款連結到ECpay的畫面 
Drupal Commerce 介紹與綠界 ECPay 金流串接實戰
Drupal Commerce 是什麼?
Drupal Commerce 是建構在 Drupal 上的開源電子商務模組，可以設計商品頁面、並提供訂單、結帳串接API實現自主的金流（不會被平台抽成），也能和原本的網站內容、會員、權限、Views 無縫結合。它由 Centarro 主導維護，目前主力版本為Commerce 3.x，支援 Drupal 10.3 以上與 Drupal 11。
它的定位並非「開箱即用的商店」，而是「可組裝的電商框架」，很適合需要客製流程、內容與商品深度整合、或與既有系統（ERP、會員系統）串接的專案。 我們把Drupal Commerce跟其他大家熟悉的平台做比較，就可以發現它除了可以用在一般電商之外，它更適合定位在B2B的商務市場。
| 平台 | 類型 | 適合情境 | 客製彈性 |
|---|---|---|---|
| Drupal Commerce | 開源框架（自架） | 內容導向電商、複雜商品/流程、B2B | 很高 |
| WooCommerce | WordPress 外掛（自架） | 中小型商店、快速上線 | 中 |
| Shopify | SaaS | 標準零售、不想管主機 | 低到中 |
| SHOPLINE / 91APP | 台灣在地 SaaS | 在地金物流整合、行銷工具 | 低 |
對已經以 Drupal 經營網站的客戶而言，Commerce 最大的價值是不需要另建一套商店系統，會員、內容與訂單都在同一個後台。
核心架構
Drupal Commerce 由幾個各司其職的子模組組成，理解它們的分工，就能看懂金流要接在哪裡。
| 模組 | 負責什麼 | 串金流時的關聯 |
|---|---|---|
| Store（commerce_store） | 商店本身：幣別、稅制、地址 | 幣別需設為 TWD |
| Product（commerce_product） | 商品與變體（Variation）：SKU、價格、屬性 | 商品名稱會帶入綠界 ItemName |
| Order（commerce_order） | 訂單、訂單項目、狀態流程（Workflow） | 付款成功後訂單轉為 completed |
| Cart（commerce_cart） | 購物車，實際上是 draft 狀態的訂單 | — |
| Checkout（commerce_checkout） | 結帳流程與各個結帳窗格（Pane） | 「付款」步驟會導向綠界 |
| Payment（commerce_payment） | 金流閘道（Gateway）、付款紀錄、退款 | 綠界模組就是一個 Gateway 外掛 |
| Price / Promotion / Tax | 價格計算、促銷、稅金 | 金額需為整數新台幣 |
| Shipping（contrib） | 運送方式與運費 | 超商取貨另需物流串接 |
Payment 模組把金流閘道分成兩類，這是串接設計的關鍵：
- On-site（站內）：信用卡資料在自己的結帳頁輸入，再透過 API 或 Token 送到金流商，例如 Stripe。網站需處理更多 PCI DSS 責任。
- Off-site（站外導向）：結帳時把消費者導到金流商的付款頁，付完再導回網站，卡號從不經過我方伺服器。綠界 全方位金流（AIO）就是這一類，在 Commerce 裡對應 OffsitePaymentGatewayBase。
Off-site 閘道有三個重要的回呼點：onReturn() 處理消費者瀏覽器導回、onCancel() 處理取消、onNotify() 處理金流商伺服器端的背景通知（Webhook）。後面的串接流程，基本上就是把綠界的規格對應到這三個方法。
為什麼要串接綠界 ECPay
在台灣第三方支付平台，有綠界科技、藍新金流..提供代收代付的服務。本文僅以綠界為例，你也可以使用藍新金流。綠界一次串接就能取得信用卡、ATM 虛擬帳號、超商代碼等在地付款方式。另外，Drupal Commerce 官方生態以國外的 Stripe、PayPal、Braintree為主，這些跨境的金流，在台灣境內的交易不能使用，必須使用政府核可的金流公司才可以交易。
綠界「全方位金流（All-In-One, AIO）」的付款方式大致如下：
| 付款方式 | ChoosePayment 值 | 付款結果何時確定 | 對訂單流程的影響 |
|---|---|---|---|
| 信用卡（含分期、定期定額） | Credit | 當下授權 | 即時完成，最容易處理 |
| ATM 虛擬帳號 | ATM | 消費者日後轉帳 | 先取號、後入帳，訂單需「待付款」狀態 |
| 超商代碼 | CVS | 消費者到超商繳費 | 同 ATM，有繳費期限 |
| 超商條碼 | BARCODE | 消費者到超商繳費 | 同 ATM |
| 網路 ATM | WebATM | 當下完成 | 需讀卡機，使用率低 |
| 全部由消費者選 | ALL | 依所選方式 | 最常用的設定 |
從架構角度看，最需要注意的是 ATM 與超商這類「非即時」付款：消費者從綠界導回網站時只拿到繳費帳號或代碼，錢還沒到。真正的入帳結果可能幾小時或幾天後才透過背景通知送達，所以訂單狀態絕不能只靠瀏覽器導回來判斷。
此外，綠界另有電子發票與物流（超商取貨）API，是和金流分開的串接。本文只處理金流。
串接前準備
1. 取得三組金鑰
綠界以 MerchantID（特店編號）、HashKey、HashIV 三個值識別商店並產生檢查碼。開發階段使用綠界開發者文件提供的公開測試帳號即可（例如常見的測試特店 3002607，實際數值請以官方最新文件為準）；正式上線前需申請特店、完成審核，再到廠商後台取得正式金鑰。正式金鑰不應寫進版控，建議放在 settings.php 的 config override 或環境變數。
2. 區分兩個環境
| 環境 | 付款頁網址 | 用途 |
|---|---|---|
| 測試(test) | payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5 | 開發與驗收，不會真的扣款 |
| 正式(live) | payment.ecpay.com.tw/Cashier/AioCheckOut/V5 | 上線後使用 |
在 Commerce 裡，這對應到金流閘道設定中的 Mode（test / live），切換模式時金鑰也要一併更換。
3. 主機環境需求
- 綠界得能連到你的網站：付款結果是由綠界伺服器主動 POST 到 ReturnURL，localhost 或只在內網的開發機收不到。本機開發可用 cloudflared 等通道工具，或直接在有公開網址的測試站上開發。
- HTTPS 與標準埠號：使用有效憑證（Let's Encrypt 即可），回呼網址走 80/443。
- 防火牆與 WAF：若前端有 FortiGate、Cloudflare 或 ModSecurity，要確認不會擋下綠界的 POST。通知被擋是「付了錢但訂單沒更新」最常見的原因。
- 時區與時間同步：MerchantTradeDate 以台灣時間（Asia/Taipei）計算，確認 PHP 與系統時區一致、NTP 正常。
- 程式層：Drupal 10.3+ / 11、Commerce 3.x（或 2.x）、PHP 8.1+，以 Composer 管理模組。
4. 商店基本設定
Store 幣別設為 TWD，並確認價格、運費、促銷計算後的總額為整數。綠界的 TotalAmount 只接受整數，小數點會直接導致交易失敗。
串接步驟
整個串接可以拆成七個步驟：安裝模組、建立閘道、調整結帳流程、組付款參數、計算檢查碼、處理背景通知、處理瀏覽器導回。前三步是設定，後四步是模組內部在做的事，理解它們才能在出問題時快速排錯。
綠界 AIO 付款流程 · 7 個步驟
消費者的瀏覽器在 Drupal 與綠界之間來回兩趨，但訂單是否已付款，只由步驟 4 的伺服器背景通知決定。
步驟一：安裝模組
特別感謝 Jiajun Xu 為Drupal 11開發ECpay 模組
Commerce_ecpay_allinone Gitlab網址
由於packages.drupal.org 目前只有 1.x-dev，還沒收錄 2.0.x 分支。要讓 Composer 直接從 drupalcode 的 Git 抓取，須先編輯網站根目錄內的composer.json的repositories區塊中，把 drupalcode 的 Git 來源加在 packages.drupal.org前面，如下圖
接著安裝commerce_ecpay_allinone
然後到後台把ECpay模組安裝好。最後再清除快取
步驟二：建立金流閘道
到「Commerce → 設定 → 付款 → 金流閘道」（/admin/commerce/config/payment-gateways）新增閘道，選擇綠界外掛，填寫：
- 模式：Test（開發階段）或 Live
- MerchantID、HashKey、HashIV
- 開放的付款方式（ChoosePayment）、ATM 繳費期限、超商代碼有效時間
- 條件（Conditions）：可限制只有特定商店、幣別或金額範圍才顯示綠界
步驟三：調整結帳流程
到「結帳流程」（/admin/commerce/config/checkout-flows）確認預設流程包含「付款資訊」與「付款處理」兩個窗格。「付款處理」在 Off-site 閘道會產生一個自動送出的表單，把消費者帶到綠界付款頁。另外要決定訂單在「下單但尚未付款」時的狀態，ATM、超商付款特別需要這個中間狀態。
步驟四：增加付款閘道Ecpay並設定付款參數
最後測試購買流程與金流付款成功畫面如下
最後付款連結到ECpay的畫面