タグアーカイブ Checkout Fees for WooCommerce

WooCommerce 決済手数料が大文字IDで効かない時の直し方

WooCommerce で「Checkout Fees for WooCommerce」などのプラグインを使い、支払い方法ごとに手数料を設定しているのに、特定の決済ゲートウェイだけルールがまったく反応しない。大文字を含む ID を持つ決済方法でこの症状が出ているなら、プラグイン内部の ID 比較処理で大文字と小文字が一致せずに無視されている可能性が高い。functions.php に1行のフィルターフックを追加するだけで即座に解消する。

なぜ特定の決済方法だけ手数料や割引が適用されないのか

Checkout Fees for WooCommerce は、支払い方法の ID をキーにして「どのゲートウェイに手数料をのせるか」を管理している。設定画面でルールを保存するとき、プラグインは WordPress の sanitize_key() 関数を通して ID をすべて小文字に変換し、データベースに格納する。ところが実際のチェックアウト画面で選択された決済方法の ID を取得する段階では、この小文字化（正規化）が行われない。

その結果、もともと ID が小文字のみで構成されているゲートウェイ（例 wc_zibal）は、保存値と取得値が同じ文字列になるため問題なく動く。一方で WC_Sep_Payment_Gateway や WC_Gateway_TorobPay のように大文字を含む ID の場合、保存された wc_sep_payment_gateway というキーと、実際にチェックアウト時に渡される WC_Sep_Payment_Gateway という文字列が一致せず、該当するルールが「存在しない」と判定されてしまう。

手数料設定が反応しない原因を視覚的に理解する

functions.php にフィルターフックを追加して即座に解決する手順

プラグイン本体のコードを直接編集しなくても、子テーマの functions.php に数行のコードを追加するだけでこの問題は修正できる。以下のフィルターフックは、チェックアウト時に渡されるゲートウェイ ID を sanitize_key() で小文字に揃え、プラグインが正しくルールを照合できるようにする。

追加するコード

add_filter( 'alg_wc_add_default_gateway_on_cart', function ( $gateway ) {
    return sanitize_key( $gateway );
} );

このフィルターフックは、プラグインが決済ゲートウェイの ID を参照する直前に割り込み、ID を小文字だけの文字列に変換する。もともと小文字のゲートウェイには何の影響も与えず、大文字を含む ID だけが正規化される。コードを追加したあとは、WooCommerce のシステムステータス画面から Transients（一時データ）を削除するか、WP Rocket や W3 Total Cache などのキャッシュプラグインを使っているなら全キャッシュのクリアを忘れない。

どうしても functions.php を触りたくない場合の代替手段

コードの追加に抵抗がある場合、Code Snippets プラグインをインストールして同じコードをスニペットとして登録する方法も有効だ。管理画面の「スニペット」→「新規追加」から上記のコードを貼り付け、「サイトのフロントエンドで実行」を選択して有効化すれば、テーマファイルを直接編集せずに済む。

決済ゲートウェイごとの手数料が今後も安定して動くようにするために

このバグは Checkout Fees for WooCommerce の無料版に限らず、同様の仕組み（sanitize_key で保存し、未正規化の ID と比較する）を持つ他の手数料系プラグインでも発生しうる。ID に大文字を使う決済ゲートウェイは海外のプロバイダーに多く見られ、特に中東やアジア圏のローカル決済サービスを WooCommerce に追加している場合に遭遇しやすい。

根本的にはプラグイン開発元が比較処理の前段で正規化を実装することが望ましいが、今回紹介したフィルターフックを適用しておけば、プラグインのアップデート後も変更が上書きされる心配はほぼない（functions.php または Code Snippets に追加したコードはプラグイン更新の影響を受けない）。

また、新しく決済ゲートウェイを追加したときにも同じ問題が起きるか事前にチェックする習慣をつけると、売上に直結するチェックアウト画面のトラブルを未然に防げる。テスト用の注文を入れて手数料が正しく加算されるか、割引が適用されるかを確認しておく。

よくある質問

この修正は Checkout Fees for WooCommerce の有料版でも必要か

本記事執筆時点では、無料版と有料版でゲートウェイ ID の正規化ロジックに違いは確認されていない。有料版でも同様に大文字混在の ID でルールが動作しなくなる場合があるため、症状が出たら同じフィルターフックを試して問題ない。

すべて小文字の ID しか使っていないが、念のためコードを追加しても害はないか

sanitize_key() はすでに小文字の文字列には何も変更を加えない。もともと正常に動いている環境にコードを追加しても、挙動が変わることは一切なく、安全に設置できる。

functions.php を編集したら画面が真っ白になった

PHP の構文エラーが原因で「このサイトで重大なエラーが発生しました」と表示されることがある。コードの貼り付け位置やセミコロンの抜けを確認する。FTP やホスティングのファイルマネージャーで functions.php を開き、追加したコードをいったん削除して復旧させてから、Code Snippets プラグイン経由で再度追加するほうが安全だ。

カスタマイズしたコードがプラグインのアップデートで消えたりしないか

子テーマの functions.php に書いたコードや Code Snippets プラグインに登録したスニペットは、プラグイン本体のアップデートとは完全に独立して保存される。アップデートのたびに再設定する必要はない。

別の手数料プラグインでも同じ現象が起きるか

ゲートウェイ ID を sanitize_key() で保存し、比較時に正規化していないプラグインであれば、同様の不具合が起こる。WooCommerce の決済ゲートウェイ関連プラグインは広くこの設計パターンをとっており、大文字を含む ID を持つ決済手段を導入したとたん手数料が効かなくなる、という報告は定期的に見られる。

この記事のポイント

• 大文字を含む決済ゲートウェイ ID で手数料が効かないのは、保存時と取得時の文字列の不一致が原因
• functions.php に1行のフィルターフックを追加すれば、即座に大文字・小文字の差を吸収できる
• コード編集が不安なら Code Snippets プラグインを使うと同じ修正を安全に適用できる
• プラグインのアップデートや新しい決済手段の追加時に備えて、テスト注文での動作確認を習慣化する