解決Woocommerce stripe的apple pay支付時錯誤問題 Payment failed: Missing required customer field: address->state - TAN-studio 香港網頁設計 - 香港HK WordPress, OpenCart, Shopify...

Payment failed: Missing required customer field: address->state 訂單狀態由 等待付款中 變更為 失敗. 這個錯誤「Payment failed: Missing required customer field: address->state」在香港地區使用 WooCommerce + Stripe + Apple Pay 時非常常見，主要原因是 Apple Pay 傳送香港地址的格式與 Stripe/WooCommerce 預期的不同，導致「州/省 (state)」欄位被判斷為缺少。

為什麼香港會特別容易出現這個問題？

• 香港地址沒有傳統的「州/省」概念（不像美國有 California、中國大陸有省份）。
• Apple Pay 在香港會把「地區」（例如 New Territories、Kowloon、Hong Kong Island）錯誤地放到 postalCode 欄位，而不是放到 region/state 欄位。
• Stripe 的 WooCommerce 插件在驗證時要求 billing address 的 state 欄位必須存在，於是就報錯「Missing required customer field: address->state」。

這個問題從 2018 年開始就陸續有 GitHub issue 回報（例如 #723、#1630、#2333、#2618 等），到 2023–2025 年仍然有香港用戶遇到，顯示官方插件尚未完全完美解決所有香港地址變體。

目前最有效的解決方法（2026 年最新建議）

1. 優先推薦：使用 WooPayments（官方推薦）
   • WooPayments 是 WooCommerce 官方出品的支付插件（基於 Stripe），對 Apple Pay + 香港地址的處理比舊的 woocommerce-gateway-stripe 插件更好。
   • 許多香港用戶反饋切換到 WooPayments 後，Apple Pay 就能正常通過。
   • 操作步驟：
     • 停用原本的 Stripe 插件（不要刪除，先停用即可）。
     • 安裝並啟用 WooPayments（在 WordPress 插件庫搜尋 “WooPayments”）。
     • 連接到你的 Stripe 帳號（同一個 Stripe 帳號可以共用）。
     • 啟用 Apple Pay / Google Pay。
   • 大部分情況下就能解決 state missing 的問題。
2. 如果不想換插件，可以試以下 workaround（舊 Stripe 插件）

   • 方法 A：強制把香港的 state 設為固定值（最常用 hack） 在你的主題 functions.php 或自訂 plugin 加入以下程式碼：

     PHP

     add_filter('woocommerce_stripe_params', function($params) {
         if (isset($params['country']) && $params['country'] === 'HK') {
             $params['state'] = 'Hong Kong';  // 或 'Kowloon'、'New Territories' 等，看你想固定哪個
         }
         return $params;
     });
     
     // 或者更強力一點，直接 bypass state 驗證（小心使用）
     add_filter('woocommerce_get_country_locale', function($locale) {
         $locale['HK']['state']['required'] = false;
         $locale['HK']['state']['hidden']   = true;
         return $locale;
     });

   • 方法 B：讓客戶在結帳頁手動填寫 state

     • 前往 WooCommerce → 設定 → 一般 → 預設客戶位置 → 選擇「香港」
     • 確保結帳表單的「州/縣」欄位是顯示且必填的。
     • 但 Apple Pay 本身不會讓客戶填寫，所以效果有限，通常還是需要上面的程式碼配合。

推薦修正方案（從最有效到次之）

1. 改用這個更針對後端驗證的 filter（最有效 workaround） 直接把香港的 state 欄位設為非必填，並可隱藏它。這會讓 WooCommerce 在驗證時跳過 state required 檢查。

   在 WPCode 新增一個新的 PHP snippet（或覆蓋舊的），貼上以下程式碼：

   PHP

   add_filter('woocommerce_get_country_locale', function($locale) {
       // 針對香港 (HK)
       $locale['HK']['state'] = array(
           'required' => false,
           'hidden'   => true,     // 隱藏 state 欄位，避免前端顯示
           'priority' => 0,        // 可選，降低優先級
       );
   
       // 可選：如果 postalCode 被誤用，也可調整
       $locale['HK']['postcode'] = array(
           'required' => false,
           'hidden'   => false,
           'label'    => __('District / Area', 'woocommerce'),
       );
   
       return $locale;
   });
   
   // 額外加強：如果還是卡，強制在 Stripe 處理前補 state
   add_filter('wc_stripe_generate_payment_request', function($request, $order) {
       if ($order->get_billing_country() === 'HK' && empty($request['shipping']['address']['state'])) {
           $request['shipping']['address']['state'] = 'Hong Kong'; // 或 'Kowloon' 等
       }
       if ($order->get_billing_country() === 'HK' && empty($request['billing']['address']['state'])) {
           $request['billing']['address']['state'] = 'Hong Kong';
       }
       return $request;
   }, 10, 2);
   • 保存後，清除網站快取（如果有 WP Rocket、LiteSpeed 等）。
   • 用 iPhone Safari 重新測試 Apple Pay（記得用真機，真實 Apple Pay 錢包）。
   • 這個組合在多個 GitHub issue（如 #2618、#1630）被證實對香港有效。

2. 如果上面還是不行，試這個更強的 bypass（小心使用，只限 HK） 有些用戶回報需要直接修改 Stripe 插件的驗證，但不建議改核心檔案。用以下 filter 強制忽略 state missing 錯誤（僅限測試，生產環境風險自負）：

   PHP

   add_filter('woocommerce_stripe_validate_checkout', function($data, $errors) {
       if (isset($data['billing_country']) && $data['billing_country'] === 'HK') {
           // 移除 state required 錯誤
           foreach ($errors->errors as $key => $error) {
               if (strpos($key, 'state') !== false || strpos($error[0], 'state') !== false) {
                   unset($errors->errors[$key]);
               }
           }
       }
       return $data;
   }, 999, 2);

   🌟最後：如果還是懶得搞，考慮使用我們提供的插件 -》在線支付 – 信用卡, Apple Pay, Google Pay