「別讓金流卡關=業績雪崩！」WordPress ECPay/HitPay API 串接終極實戰：從安全驗證到非同步通知的滴水不漏架構

哈囉，我是浪花科技的資深工程師 Eric。今天不聊什麼高大上的 AI 或分散式架構，我們來聊點最接地氣，也最容易讓你半夜被客戶 call 醒的議題——金流。沒錯，就是那個使用者按下滑鼠，錢錢應該要流進你口袋，但偏偏就在某個環節卡住的「第三方支付 API 串接」。

你可能心想：「Eric，這不是裝個 WooCommerce 外掛就能解決的事嗎？」嗯，理想情況是這樣沒錯。但現實是，當你的業務邏輯稍微複雜一點，例如需要客製化的結帳流程、需要將訂單資料即時同步到 ERP 或 CRM、或是你用的那個金流外掛剛好跟某個關鍵外掛打架時…恭喜你，你就踏入了「手刻 API 串接」這個充滿挑戰但也更有價值的領域。

這篇文章不是要教你複製貼上程式碼，而是要帶你建立一個「工程師等級」的思維框架。我們要探討的，是如何在 WordPress 上，打造一個不只「能動」，更是「穩固」、「安全」、「可信賴」的金流串接系統，這次我們以台灣常見的 ECPay (綠界) 和東南亞新星 HitPay 為例，深入探討其中的魔鬼細節。

為何不直接用現成外掛？工程師的「控制狂」視角

好了，身為一個資深工程師，我得先囉嗦幾句。市面上的金流外掛琳瑯滿目，為什麼我們有時候還是得撩起袖子自己幹？

• 效能與臃腫 (Bloat)： 很多 All-in-One 的外掛為了相容各種情境，載入了大量你根本用不到的程式碼和 CSS/JS 檔案，無形中拖慢了你網站的速度。在分秒必爭的結帳頁面，每慢一秒都可能流失一筆訂單。
• 客製化彈性： 你的老闆或行銷團隊是不是常常有天馬行空的想法？「我希望會員等級不同，結帳時的付款選項也不同」、「我希望付款成功後，不只更新訂單，還要觸發一個 HubSpot 的 workflow」。這些高度客製化的需求，用現成外掛往往綁手綁腳，最後還是得用醜陋的方式硬幹 (hardcode)，埋下未來的技術債。
• 安全性與掌控權： 當你把攸關金錢的關鍵流程交給第三方外掛，等於是將一部分的信任交了出去。如果外掛有漏洞（這比你想像的更常見），你的網站就可能暴露在風險之中。自己串接，意味著每一行程式碼都在你的掌控之內，你可以用最嚴格的標準來審視它。
• 除錯的透明度： 用外掛遇到問題，你可能只能回報給作者，然後無盡地等待更新。自己寫的程式碼，你可以加上完整的 Log 紀錄，從發送請求、接收通知到更新訂單的每一步都一清二楚。出問題時，你不是瞎子摸象，而是有跡可循的外科醫生。

當然，我不是說外掛不好。對於標準的電商網站，它們是快速上線的絕佳選擇。但當你的網站開始成長，業務變得複雜，「掌控權」就會成為你最寶貴的資產。

決戰前夜：ECPay / HitPay API 核心概念解析

在動手寫 Code 之前，我們必須先搞懂所有第三方支付 API 的共同語言。無論是 ECPay、HitPay 還是 Stripe、NewebPay，它們的運作邏輯都大同小異，核心圍繞著以下幾個概念：

1. 交易的「數位簽章」：CheckMacValue / Signature

這是整個流程中最最最重要的一環。當你把訂單金額、訂單編號等資訊送給金流商時，為了防止這些資料在傳輸過程中被惡意竄改（例如駭客把 1000 元改成 1 元），你需要用一把只有你和金流商知道的「鑰匙」（Hash Key / Hash IV）將所有參數加密成一組獨一無二的「簽章」（ECPay 稱之為 CheckMacValue，HitPay 稱之為 Signature）。金流商收到後，會用同樣的方式再算一次，如果兩邊的簽章對不上，交易就直接失敗。這確保了資料的完整性與來源的可靠性。

2. 兵分兩路：同步通知 (ReturnURL) vs. 非同步通知 (Webhook/NotifyURL)

這是最多新手工程師會踩的坑！

• 同步通知 (ReturnURL / ClientBackURL)： 當使用者在金流頁面完成付款後，「瀏覽器」會被導回你指定的頁面（例如「感謝訂購」頁）。千萬、千萬、千萬不要 在這個環節更新你的訂單狀態！因為使用者可能付完款就關掉瀏覽器，或網路突然中斷，導致這個導向沒有發生。如果你只依賴這個通知，就會造成「客戶付了錢，訂單卻還是待付款」的悲劇。
• 非同步通知 (Webhook / PaymentInfoURL / NotifyURL)： 這才是真正可靠的溝通方式。當金流商確認收到款項後，是他們的「伺服器」在背景，直接對你指定的另一個網址（Webhook）發出一個 POST 請求，告訴你「這筆訂單成功了」。這個過程跟使用者的瀏覽器完全無關，即使他的電腦爆炸了，只要金流商收到錢，這個通知就一定會發出。所有訂單狀態的更新、庫存的扣減、觸發後續流程，都應該在這裡完成。

WordPress 實戰：打造堅不可摧的金流處理流程

理論講完了，我們來點實際的。假設我們要為 WooCommerce 訂單手動串接 ECPay。

Step 1: 安全第一！建立訂單與產生加密參數

當使用者按下「下單購買」時，我們可以掛載在 `woocommerce_checkout_process` 或 `woocommerce_new_order` 這個 hook 上。我們的目標是蒐集必要的訂單資訊，並產生那組關鍵的 CheckMacValue。

<?php
// 記得將 HashKey 和 HashIV 存在 wp-config.php 中，不要寫死在程式碼裡！
// define('ECPAY_HASH_KEY', 'your_hash_key');
// define('ECPAY_HASH_IV', 'your_hash_iv');

function generate_ecpay_checksum($params) {
    // 1. 依 ECPay 規定，將參數依字母排序
    ksort($params);

    // 2. 組成 URL Query String
    $queryString = http_build_query($params);

    // 3. 加上 HashKey 和 HashIV
    $queryString = 'HashKey=' . ECPAY_HASH_KEY . '&' . $queryString . '&HashIV=' . ECPAY_HASH_IV;

    // 4. URL Encode 後轉小寫
    $queryString = urlencode($queryString);
    $queryString = strtolower($queryString);

    // 5. 用 SHA256 加密後轉大寫
    $checksum = strtoupper(hash('sha256', $queryString));

    return $checksum;
}

// 在訂單建立後
add_action('woocommerce_new_order', 'create_ecpay_payment_form', 10, 1);
function create_ecpay_payment_form($order_id) {
    $order = wc_get_order($order_id);
    
    $trade_no = 'ROAMER' . time() . $order_id; // 建立唯一的訂單編號
    $order->update_meta_data('_ecpay_trade_no', $trade_no);
    $order->save();

    $params = [
        'MerchantID' => 'your_merchant_id',
        'MerchantTradeNo' => $trade_no,
        'MerchantTradeDate' => date('Y/m/d H:i:s'),
        'PaymentType' => 'aio',
        'TotalAmount' => $order->get_total(),
        'TradeDesc' => '浪花科技商品一批',
        'ItemName' => '商品名稱 #',
        'ReturnURL' => home_url('/your-thank-you-page/'), // 同步通知
        'ChoosePayment' => 'ALL',
        'EncryptType' => 1,
        'ClientBackURL' => home_url('/your-order-list/'),
        'PaymentInfoURL' => home_url('/wp-json/roamer-payment/v1/ecpay-notify') // 非同步通知！
    ];

    $params['CheckMacValue'] = generate_ecpay_checksum($params);

    // 接下來就是產生一個自動提交的 form，將使用者導向 ECPay
    // ... 程式碼省略
}
?>

Step 2: 建立接收非同步通知的 API 端點 (Webhook)

這一步是重中之重。我們需要用 WordPress 的 REST API 功能，建立一個專門接收 ECPay 伺服器通知的端點。

<?php
add_action('rest_api_init', function () {
    register_rest_route('roamer-payment/v1', '/ecpay-notify', [
        'methods' => 'POST',
        'callback' => 'handle_ecpay_notify',
        'permission_callback' => '__return_true' // 暫時開放，正式環境應加上 IP 白名單等驗證
    ]);
});

function handle_ecpay_notify(WP_REST_Request $request) {
    $data = $request->get_params();
    
    // 關鍵第一步：驗證 CheckMacValue
    $received_checksum = $data['CheckMacValue'];
    unset($data['CheckMacValue']);
    $calculated_checksum = generate_ecpay_checksum($data);

    if ($received_checksum !== $calculated_checksum) {
        // 寫入 Log: 簽章驗證失敗
        error_log('ECPay Notify Error: Checksum mismatch. Order No: ' . $data['MerchantTradeNo']);
        return new WP_Error('checksum_error', 'Checksum mismatch', ['status' => 400]);
    }

    // 關鍵第二步：驗證交易狀態
    if ($data['RtnCode'] !== '1') {
        // 寫入 Log: 交易失敗
        error_log('ECPay Notify Error: Payment failed. RtnCode: ' . $data['RtnCode'] . ' Order No: ' . $data['MerchantTradeNo']);
        // 可以在這裡更新訂單為失敗狀態
        return ['status' => 'failed', 'message' => $data['RtnMsg']];
    }

    // 從 MerchantTradeNo 反查我們自己的訂單 ID
    $trade_no = $data['MerchantTradeNo'];
    // ... 透過 $wpdb 查詢 meta data _ecpay_trade_no 找到 order_id
    $order = wc_get_order($order_id);

    if (!$order) {
        error_log('ECPay Notify Error: Order not found for Trade No: ' . $trade_no);
        return new WP_Error('order_not_found', 'Order not found', ['status' => 404]);
    }

    // 關鍵第三步：防止重複處理 (Idempotency)
    if ($order->is_paid()) {
        error_log('ECPay Notify Info: Order already paid. Trade No: ' . $trade_no);
        // 必須回傳 '1|OK' 讓 ECPay 知道你收到了，不然他會一直重送
        echo '1|OK';
        exit;
    }

    // 一切驗證通過，更新訂單狀態！
    $order->payment_complete($data['TradeNo']); // 傳入金流商的交易編號
    $order->add_order_note('付款成功！ECPay 交易序號：' . $data['TradeNo']);
    $order->save();

    // 記得要回傳 '1|OK' 給 ECPay，否則它會認為你沒收到，然後瘋狂重試！
    echo '1|OK';
    exit;
}
?>

工程師的囉嗦時間：那些課本沒教的魔鬼細節

• 冪等性 (Idempotency)： 你注意到了嗎？在更新訂單前，我先檢查了 `$order->is_paid()`。網路不穩或金流商系統的關係，他們有可能在短時間內重複發送同一個通知。你必須確保你的程式碼執行一次和執行一百次的結果是完全一樣的，這就是冪等性。不然客戶只付了一次錢，你卻寄了兩次貨，那就尷尬了。
• 日誌 (Logging) 是一切： 在程式的每個關鍵判斷點，特別是錯誤發生的時候，用 `error_log()` 把詳細資訊寫下來。當客戶抱怨「我付了錢但訂單沒成功」時，Log 是你唯一的救贖。你可以清楚地看到是 ECPay 沒發通知，還是你這邊簽章算錯，或是訂單找不到。
• 資料庫交易 (Transaction)： 在更嚴謹的系統中，更新訂單狀態、扣庫存、新增備註等一系列資料庫操作，應該被包在一個「交易」裡。這確保了所有步驟要嘛全部成功，要嘛全部失敗，不會發生訂單狀態改了但庫存沒扣到的情況。這部分可以參考我們關於 WordPress 資料庫 Transaction 與 Lock 機制 的文章。
• 安全性強化： 在 `register_rest_route` 的 `permission_callback` 中，你不應該只是 `__return_true`。正式環境上，你應該要去 ECPay 後台查詢他們的通知伺服器 IP，並設定白名單，只允許來自這些 IP 的請求，防止駭客偽造通知。

HitPay 的串接邏輯也完全相同，只是參數名稱、簽章的加密方式（通常是 HMAC-SHA256）和回傳的成功訊息不一樣。但只要你掌握了「產生簽章 -> 導出 -> 建立 Webhook -> 驗證簽章 -> 更新訂單」這個核心流程，任何金流你都能迎刃而解。

結論：不只是串接，更是打造穩固的商業核心

手動進行第三方支付 API 串接，從來都不只是一件「技術活」。它考驗的是你對整個商業流程的理解，對各種異常情況的預判，以及對系統穩定性與安全性的執著。當你完成一個滴水不漏的金流系統時，你獲得的不只是一項功能，更是客戶的信任與公司營運的穩定基石。

這過程很燒腦，但成就感也是巨大的。從此以後，你不再害怕任何客製化的金流需求，因為你已經掌握了它的核心命脈。

相關閱讀

• 結帳又失敗？庫存又超賣？資深工程師帶你拆解 WordPress 資料庫死結 (Deadlock) 與競爭條件 (Race Condition) 的隱形殺手
• 你的 WordPress 正在大開後門嗎？資深工程師的 Webhook 設計與安全驗證終極指南
• 你的 Code 在哭泣！資深工程師帶你用 $wpdb->prepare() 徹底根治 WordPress SQL Injection 漏洞

如果你在金流串接或任何 WordPress 系統整合上遇到了瓶頸，或是希望打造一個真正能支撐你業務成長的客製化系統，別只是埋頭苦幹。浪花科技的團隊擁有豐富的實戰經驗，能幫你從架構設計到程式碼實作，打造最穩固的解決方案。歡迎點擊這裡，填寫表單與我們聯繫，讓我們一起聊聊你的挑戰！