金流串接不再頭痛！WordPress 第三方支付 API 終極實戰 (ECPay + HitPay 全攻略)

嗨，我是浪花科技的資深工程師 Eric。在 WordPress 的世界裡打滾了這麼多年，從簡單的部落格到複雜的電商平台，我看過太多客戶為了一件事傷透腦筋——那就是「錢」。更準確地說，是如何在網站上安全、穩定地收錢。這就是我們今天要深入探討的主題：第三方支付 API 串接實作。

你可能已經在用 WooCommerce，也可能裝了某個金流外掛，但你有沒有想過，如果能更深一層地理解背後的運作原理，甚至自己動手串接，你的網站將會有多大的彈性？今天，我就要帶你撩起袖子，直接面對金流串接的核心，我們將以台灣最普及的 ECPay (綠界) 和一個適合國際收款的 HitPay 為例，從觀念到實作，一次讓你搞懂 WordPress 的金流整合黑魔法。

為什麼不直接用現成外掛就好？談談手動串接 API 的好處

在我們開始之前，我得先來段工程師的小囉嗦。我知道，我知道，市面上有那麼多現成的金流外掛，裝上去、設定一下 Merchant ID 跟 Key，按幾下就搞定了，快又有效。那為什麼我們還要自討苦吃，去研究什麼 API 文件、寫程式碼呢？

身為一個對程式碼有點潔癖的工程師，有時候看到外掛為了相容各種情境，包山包海地載入一堆我根本用不到的 JavaScript 和 CSS 檔案，或是後台設定頁面複雜到像在開飛機，心裡總是有點過不去。手動串接 API 帶來的好處是：

• 極致的客製化： 你可以完全掌控付款流程的每一個環節，打造最貼合你品牌風格與使用者體驗的結帳頁面，而不是被外掛的版面綁架。
• 輕量與高效能： 沒有多餘的程式碼，只載入你需要的東西。對於追求網站速度的我們來說，每一毫秒都至關重要。
• 更強的除錯能力： 當金流出問題時，因為整個流程是你親手打造的，你能夠更快速地定位問題點，而不是在外掛的程式碼海中迷航。
• 學習與成長： 搞懂金流 API 的運作，絕對會讓你的 WordPress 開發功力提升一個檔次。

當然，這條路需要你對 PHP 和 WordPress 的運作有基本的了解。但相信我，走完這一遭，你會很有成就感。

開工前的準備：打好地基，才能蓋高樓

在我們開始撰寫任何程式碼之前，請確保你已經準備好以下幾樣東西，這就像蓋房子前的地基，缺一不可：

• 一個正常的 WordPress 環境： 這可以是你的本機開發環境，或是測試用的主機。
• SSL 憑證 (HTTPS)： 這不是選項，是絕對的標配！任何跟金錢交易有關的傳輸，都必須在 HTTPS 的加密通道下進行，否則你就是在拿客戶的資料和你的商譽開玩笑。
• ECPay 與 HitPay 的商家帳號： 你需要先到他們的官網註冊並取得商家資格。他們通常會提供一個「測試環境」讓你開發，這非常重要，我們所有的開發與測試都應該在測試環境完成。
• API 金鑰： 這是你的網站與支付平台溝通的「鑰匙」，包含 MerchantID、HashKey、HashIV、API Key、Salt 等，等等我們會詳細說明。
• 一個好的程式碼編輯器跟你最愛的咖啡： 寫 Code 是個需要專注的過程，對吧？

決戰 ECPay：台灣電商金流串接實戰

ECPay (綠界) 幾乎是台灣電商網站的標配，支援的付款方式非常多元。它的串接方式主要是透過「表單提交 (Form Post)」來達成。

ECPay 核心流程解剖

整個流程可以簡化為以下幾個步驟：

1. 使用者在你的網站上點擊「前往付款」。
2. 你的 WordPress 網站根據訂單資訊，動態生成一個 HTML 表單，裡面包含了所有必要的交易參數，以及一個最重要的「交易檢查碼 (CheckMacValue)」。
3. 這個表單會自動提交 (POST) 到 ECPay 的伺服器。
4. 使用者在 ECPay 的頁面完成付款（輸入信用卡號、ATM 轉帳等）。
5. ECPay 處理完畢後，會做兩件事：
   a. 將使用者導回你指定的「付款完成頁 (ReturnURL)」。
   b. 在背景（Server-to-Server）發送一個通知到你指定的「回調網址 (OrderResultURL)」。
6. 你的網站收到這個背景通知後，再次驗證檢查碼，確認通知的合法性，然後更新訂單狀態。

這裡的關鍵在於 CheckMacValue，它是一個經過特殊規則加密的字串，用來確保交易資料在傳輸過程中沒有被竄改，並且真的是由你發出的。

打造送往 ECPay 的「出師表」：付款表單與簽章生成

要向 ECPay 發起一筆交易，你需要準備一堆參數，例如：MerchantID、MerchantTradeNo（訂單編號）、TotalAmount（金額）、ItemName（商品名稱）等等。而最重要的，就是產生 CheckMacValue。

ECPay 的文件寫得很清楚，它的產生規則是：將所有必要參數（不含 CheckMacValue 本身）依字母順序排序，組合成 `key=value&key2=value2` 的字串，頭尾再加上你的 HashKey 和 HashIV，然後進行 URL Encode、轉小寫，最後用 SHA256 加密。聽起來很複雜？沒關係，直接看程式碼最快：

<?php
/**
 * 生成 ECPay 的 CheckMacValue
 *
 * @param array  $params   交易參數陣列
 * @param string $hash_key ECPay 後台提供的 HashKey
 * @param string $hash_iv  ECPay 後台提供的 HashIV
 * @return string
 */
function generate_ecpay_mac($params = [], $hash_key = '', $hash_iv = '') {
    // 1. 依參數名稱的字母 A-Z 排序
    ksort($params);

    // 2. 組成 URL-encoded query string
    $query_string = http_build_query($params);

    // 3. 頭尾加上 HashKey 和 HashIV，並取代特定符號
    $string_to_hash = 'HashKey=' . $hash_key . '&' . $query_string . '&HashIV=' . $hash_iv;

    // 4. URL-encode, 轉小寫, 取代編碼後的特殊字元 (dot-net-style)
    $string_to_hash = urlencode($string_to_hash);
    $string_to_hash = strtolower($string_to_hash);
    $string_to_hash = str_replace('%2d', '-', $string_to_hash);
    $string_to_hash = str_replace('%5f', '_', $string_to_hash);
    $string_to_hash = str_replace('%2e', '.', $string_to_hash);
    $string_to_hash = str_replace('%21', '!', $string_to_hash);
    $string_to_hash = str_replace('%2a', '*', $string_to_hash);
    $string_to_hash = str_replace('%28', '(', $string_to_hash);
    $string_to_hash = str_replace('%29', ')', $string_to_hash);

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

    return $check_mac_value;
}
?>

有了這個函式，你就可以在使用者結帳時，把訂單資訊丟進去，產生 CheckMacValue，然後把所有參數渲染成一個隱藏的 HTML 表單，再用 JavaScript 自動提交它。

接收勝利的號角：處理 ECPay Server-to-Server 回調

這一步是整個流程中最容易被忽略，卻也最重要的一環。千萬不要只依賴使用者跳轉回來的 ReturnURL 來更新訂單狀態！因為使用者可能在付款成功後直接關掉瀏覽器。最可靠的做法是處理 ECPay 從伺服器端發來的 OrderResultURL 通知。

當你收到這個 POST 通知時，裡面會包含交易結果和一個回傳的 CheckMacValue。你要做的，就是用完全相同的加密規則，拿回傳的資料（不含 CheckMacValue）和你自己的 HashKey/HashIV 再算一次，比對看看兩個 CheckMacValue 是否一致。如果一致，就代表這筆通知是合法且未經竄改的，你就可以安心地去資料庫更新你的訂單狀態了。

征服 HitPay：國際金流 API 串接實戰

如果你的業務範圍不只在台灣，那麼 HitPay 就是一個不錯的選擇，它支援多國貨幣和多種支付方式（如 PayNow、GrabPay 等）。與 ECPay 不同，HitPay 主要採用 RESTful API 的方式進行串接。

HitPay API 運作邏輯

HitPay 的流程更接近現代的 API 設計：

1. 使用者在你的網站點擊「前往付款」。
2. 你的 WordPress 網站從後端（Server-side）向 HitPay 的 API 端點發起一個 POST 請求，請求中包含了交易資訊和你的 API Key。
3. HitPay API 驗證你的請求後，會回傳一個 JSON，裡面包含一個專屬的付款連結 (URL)。
4. 你的網站收到這個 URL 後，將使用者重導 (redirect) 到這個付款連結。
5. 使用者在 HitPay 的頁面完成付款。
6. HitPay 透過 Webhook (類似 ECPay 的回調)，向你指定的網址發送一個 POST 請求，通知你交易結果。
7. 你的網站接收到 Webhook，驗證簽章 (Signature) 的合法性，然後更新訂單狀態。

發起進攻：使用 `wp_remote_post` 建立付款請求

在 WordPress 中，要發起後端 API 請求，最好的方式就是使用內建的 `wp_remote_post` 函式。你需要將 API Key 放在 HTTP Header 中進行驗證。

<?php
function create_hitpay_payment_request($order_data, $api_key) {
    $api_url = 'https://api.hit-pay.com/v1/payment-requests'; // 注意測試與正式環境的 URL 不同

    $body = [
        'email'           => $order_data['email'],
        'amount'          => $order_data['amount'],
        'currency'        => 'TWD',
        'reference_number'=> $order_data['order_id'],
        'webhook'         => 'https://your-website.com/api/hitpay-webhook',
        'redirect_url'    => 'https://your-website.com/payment-thank-you',
    ];

    $args = [
        'body'    => json_encode($body),
        'headers' => [
            'Content-Type'      => 'application/json',
            'X-Business-Api-Key'=> $api_key,
        ],
    ];

    $response = wp_remote_post($api_url, $args);

    if (is_wp_error($response)) {
        // 處理錯誤
        return null;
    }

    $response_body = json_decode(wp_remote_retrieve_body($response), true);

    return $response_body; // 回傳的資料中會有 id 和 url
}
?>

成功的話，你會從 `$response_body` 中拿到一個 `url`，把使用者導過去就對了。

滴水不漏的防線：驗證 HitPay Webhook 簽章

當 HitPay 透過 Webhook 通知你時，會在 HTTP Header 裡帶一個 `X-Signature` 的欄位。這個簽章是使用 HMAC-SHA256 演算法，拿你的 API Salt 作為密鑰，對整個請求的 Body 進行加密得到的。

你的任務就是在收到 Webhook 時，用同樣的方式自己算一次簽章，然後跟 Header 裡收到的比對。這裡要囉嗦一下，請務必使用 `hash_equals()` 函式來比對字串，這可以有效防止「時序攻擊 (Timing Attack)」，是處理資安驗證時的標準做法。

<?php
function verify_hitpay_webhook($request_body_string, $signature_from_header, $api_salt) {
    $computed_signature = hash_hmac('sha256', $request_body_string, $api_salt);

    // 使用 hash_equals() 來防止時序攻擊
    return hash_equals($computed_signature, $signature_from_header);
}
?>

只有驗證通過，才能相信這筆通知的內容，並據此更新訂單。

金流串接的必修學分：安全，還是安全！

無論你用哪家金流，請務必把以下幾點刻在腦子裡：

• HTTPS 是你的生命線： 再次強調，沒有 HTTPS 就沒有交易安全。
• 永遠不要儲存信用卡號： 把處理敏感資料的責任交給專業的支付平台，這是使用第三方金流最大的好處之一。
• 後端驗證是唯一的真理： 永遠不要相信從前端 (使用者瀏覽器) 回傳的任何結果，唯一的訂單狀態更新依據，必須是經過簽章驗證的 Server-to-Server 回調/Webhook。
• 妥善保管你的金鑰： 你的 API Keys/Salts/HashIV 等，絕對不要寫死在佈景主題或外掛的程式碼裡，更不要上傳到公開的 Git repository。最好的做法是將它們定義在 `wp-config.php` 這個不會被公開存取的檔案中。

恭喜你，看到這裡，你已經對 WordPress 第三方支付 API 串接有了相當深入的了解。從 ECPay 的表單提交到 HitPay 的 RESTful API，你掌握了兩種主流的串接模式。這不僅僅是寫幾行程式碼，更是建立一個安全、可靠、客製化線上交易系統的基石。雖然過程比單純安裝外掛來得複雜，但這份對底層邏輯的掌控感，絕對是身為專業開發者的你，最寶貴的資產。

延伸閱讀

• 別再寫出連自己都看不懂的 API！資深工程師的 WordPress REST API 設計原則終極指南
• 網站半夜被黑？別怕！資深工程師的 WordPress 終極安全指南，從預防到災難復原全攻略
• LINE 官方帳號還在手動回？資深工程師帶你用 WordPress 打造 24H 全自動 LINE Chatbot！

如果你覺得自行處理金流串接太過複雜，或是你有更獨特的商業邏輯需要客製化，浪花科技的團隊擁有豐富的 WordPress 金流整合與 API 串接經驗。我們樂於協助你打造最穩定、安全的電子商務解決方案。歡迎與我們聯繫，讓專業的團隊為您的事業加速！