2025 年綠界 API 改版重點摘要：Apple Pay 開放與手續費欄位調整

2025 年 4 月 1 日，綠界實施了近年來最重要的一次 API 規格調整。這次改動涵蓋了收費模式、回傳欄位和付款方式三個層面，影響所有正在使用綠界金流的商家。如果你的系統在 2025 年 4 月之前就已經上線，務必確認是否已經完成對應的程式碼調整。

第一個改動：Apple Pay 收款功能全面自動開啟。在此之前，Apple Pay 需要商家手動申請開通。2025 年 4 月 1 日起，所有賣家（個人、商務、特約）的 Apple Pay 功能自動啟用。這代表如果你在建立訂單時設定 ChoosePayment 為 ALL，消費者在付款頁面上會看到 Apple Pay 的選項——即使你從未刻意啟用它。如果你的業務邏輯不希望提供 Apple Pay（例如你的商品不適合在行動裝置上購買），你需要在 IgnorePayment 參數中明確排除 ApplePay。

第二個改動：金流服務費計算方式從「單一百分比」調整為「手續費（百分比）+ 處理費（固定金額）」。具體來說，每筆信用卡訂單會額外收取 1 元的交易處理費。這個變動反映在 API 回傳的欄位上：原本的 PaymentTypeChargeFee 欄位定義調整為「金流服務費」（僅含百分比手續費的部分），同時新增了 ProcessFee 欄位代表「交易處理費」（固定金額）。如果你的系統有自動計算金流成本的邏輯——例如用 PaymentTypeChargeFee 來計算每筆訂單的實際利潤——你需要更新公式，將 ProcessFee 納入計算。

第三個改動影響的是對帳流程。綠界的「下載撥款對帳檔」API 回傳的 CSV 檔案中也新增了 ProcessFee 欄位。如果你有自動化的對帳腳本在解析這份 CSV，新增的欄位可能導致欄位順序偏移或解析失敗。建議以欄位名稱（Header）而非欄位位置（Index）來解析對帳檔案，這樣即使未來再新增欄位也不會受影響。

因應這三個改動，建議的系統調整步驟如下。首先，在綠界的測試環境（payment-stage.ecpay.com.tw）中驗證你的串接是否能正確處理新的回傳欄位。測試環境已在 2025 年 3 月提前上線了新規格。其次，更新你的付款結果處理邏輯，確保能正確讀取 ProcessFee 欄位。如果你的程式碼使用了強型別的資料模型（例如 TypeScript 的 interface 或 C# 的 class），記得新增這個欄位的定義。第三，檢查你的 IgnorePayment 設定，決定是否要顯示 Apple Pay 選項。第四，更新對帳腳本的 CSV 解析邏輯。最後，在正式環境上線後進行一筆小額真實交易，確認回傳資料的結構符合預期。

這次改版的影響範圍不大，但屬於「不處理就會默默出問題」的類型——你的系統不會報錯，但金流成本計算可能會不準確，Apple Pay 可能在你不預期的地方出現。主動處理永遠好過被動發現。