VibeFox ECPay for WooCommerce — ヘルプ
要件
WordPress: 6.0 以降。
WooCommerce: 8.0 以降。インストールして有効化してください。
PHP: 8.0 以降。
ストアの通貨: 新台湾ドル（TWD）。ECPay は TWD のみで課金し、ストアまたは支払い対象の注文が別の通貨を使用している場合、この決済方法は表示されません。ECPay は小数を受け付けないため、金額は整数の TWD で送信されます。注文合計は最も近いドルに四捨五入されます。四捨五入を避けるには、TWD の価格を小数点以下 0 桁に設定してください。
ECPay アカウント: 実際の決済には、ECPay 加盟店管理画面（vendor.ecpay.com.tw）から取得する ECPay 加盟店アカウントの MerchantID、HashKey、HashIV が必要です。テストには ECPay アカウントは不要です。
サイトへのアクセス: ECPay が決済通知を送信できるように、ストアのサイトはインターネットから HTTP/HTTPS でポート 80/443 にアクセス可能である必要があります。メンテナンスモード、ファイアウォール、またはサイト前段の Basic 認証があると通知がブロックされます。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_ecpay_payment_gateway フォルダーを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。WooCommerce が有効になっている必要があります。
3. 設定を開きます: WooCommerce > Settings > Payments > ECPay (綠界) > Manage、またはプラグインページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。
5. Enable/Disable をオンにし、決済方法を選択し、最初のテストでは Test Mode をオンにしておきます。サンドボックスでは、ECPay のテストカード 4311-9522-2222-2222（将来の任意の有効期限、CVV 222、サンドボックスページの 3-D Secure コード）で支払うことができます。
6. 実際の決済では MerchantID、HashKey、HashIV を入力し（「設定」を参照）、Test Mode のチェックを外します。
設定
すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > ECPay (綠界)。フィールドの上部には、ストアの通貨が TWD でない場合（この場合 ECPay はチェックアウトに表示されません）、および本番モードで MerchantID、HashKey、HashIV が設定されていない場合にエラーが表示されます。テストモードがオンになっている間は、決済が公開テスト加盟店 3002607 を使った ECPay サンドボックスに送られ、実際の金額は請求されないこと、公開サンドボックスのキーを知っていれば誰でもテスト注文を確認できてしまうことが警告されます。実際の注文を受け付ける前にはテストモードをオフにする必要があります。
一般
Enable/Disable: Enable ECPay Payment で決済方法をオン・オフします。デフォルト: オフ。
Title: チェックアウト時に購入者が見る決済方法名です。デフォルト: ECPay (綠界)。
Description: チェックアウト時に決済方法の下に表示されるテキストです。デフォルト: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode)。
ECPay アカウント
MerchantID、HashKey、HashIV は、ECPay 加盟店管理画面（vendor.ecpay.com.tw）の System development management > System integration settings（系統開發管理 > 系統介接設定）で確認できます。
Test Mode: Enable sandbox/test mode は、公開 ECPay テスト加盟店 3002607 を使って決済を ECPay サンドボックス（payment-stage.ecpay.com.tw）に送信します。実際の代金は発生しません。以下の認証情報は、テストモードがオフのときのみ使用されます。デフォルト: オン。
Merchant ID: 本番用の ECPay Merchant ID です。テストモードでは無視されます。
Hash Key: 本番用の ECPay Hash Key です。テストモードでは無視されます。
Hash IV: 本番用の ECPay Hash IV です。テストモードでは無視されます。
貼り付けた認証情報に空白や改行があるとすべての署名が壊れるため、保存時に自動的に削除され、その旨がページに表示されます。
決済オプション
Enabled Payment Methods: 購入者に提供する決済方法です。複数選択した場合、購入者はチェックアウト時に選べます。ATM、CVS、Barcode の注文は、購入者が支払うまで「保留中」のままです。少なくとも 1 つの方法を選択する必要があり、何も選択されていない場合は Credit Card が有効になります。デフォルト: Credit Card。
Default Payment Method: あらかじめ選択される方法です。有効な方法のいずれかである必要があり、そうでない場合は最初に有効な方法が使用されます。デフォルト: Credit Card。
Order Prefix: ECPay の取引番号（MerchantTradeNo）の接頭辞で、最大 5 文字の英数字です。他の文字は保存時に削除されます。複数のショップが 1 つの ECPay アカウントを共有する場合に、各ショップに独自の接頭辞を割り当てる際に便利です。デフォルト: EC。
決済通知
ECPay は決済結果をストアに送信します。このセクションには通知 URL が表示されます。次のような形式です: https://your-site/wc-api/ecpay_p_callback/。この URL はすべての決済とともに送信されるため、ECPay 側で設定する必要はありませんが、メンテナンスモード、ファイアウォール、Basic 認証がない状態でインターネットからポート 80/443 でアクセス可能である必要があります。
各通知は、決済が開始された環境（テストまたは本番）のキーを使った CheckMacValue 署名によって検証されます。有効な署名のない通知は拒否され、ECPay は再送します。通知がない場合、注文は支払済みになりません。ECPay の管理画面で決済を確認してください。
詳細設定
Enable Logging: Log payment events and API calls は、注文 ID、取引番号、金額、ECPay の戻りコードを WooCommerce > Status > Logs（ソース: wcp_ecpay_payment_gateway）に記録します。キーや購入者データは記録されません。デフォルト: オフ。
Delete Data on Uninstall: Delete all plugin data when uninstalling。このプラグインのすべての設定、ログ、注文メタデータを削除します。デフォルト: オフ。
チェックアウト
購入者は決済方法を選択します（デフォルトは ECPay (綠界)）。複数の方法が有効な場合、購入者は Credit Card、ATM (Virtual Account)、CVS (Convenience Store)、Barcode も選択します。テストモードがオンの間、決済方法には TEST MODE — ECPay sandbox, no real money is charged. と表示されます。
注文完了後、購入者には Redirecting to ECPay for payment. Please wait... と表示され、ECPay の決済ページに送られます。リダイレクトが始まらない場合に備えて Proceed to ECPay ボタンも用意されています。注文合計は、商品の名称と数量とともに整数の TWD で送信されます。ECPay のページは、台湾および香港のサイト言語では繁体字中国語、簡体字中国語、韓国語、日本語のサイト言語ではそれぞれの言語、他のすべての言語では英語で開きます。
注文が支払済みになるのは、ECPay が署名付きのサーバー通知で確認した後だけです。確認が届く前に購入者が注文受領ページに戻った場合、ページには We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: と Pay ボタンが表示されます。
ATM、CVS、Barcode の場合、購入者は最初に支払いの詳細を受け取ります。注文は「保留中」になり、銀行コードと仮想口座、コンビニ払込番号またはバーコード、金額、Pay before の日付が、サンクスページの ECPay payment instructions、My account > Orders、保留中の注文のメールに表示されます。購入者が支払うと、ECPay がもう 1 つの通知を送信し、注文が支払済みになります。
ECPay は再利用された番号を拒否するため、決済ページへのアクセスごとに新しい ECPay 取引番号が作成されます。これにより、Pay for order ページや決済失敗後の再試行が機能し、これらの番号のいずれかに対する通知は注文に一致します。1 つの注文には最大 30 回の決済試行が可能です。
コンビニ決済など、方法ごとの ECPay 独自の金額制限は、チェックアウトではなく ECPay のページで確認されます。
この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。
本プラグインは ECPay のページでの一回限りの決済のみに対応しています。WooCommerce からの返金、保存済みカード、定期購入や継続課金（定期定額）、分割払い、Apple Pay、TWQR、WeChat Pay、BNPL、WebATM、電子インボイス、物流には対応しておらず、サーバー側のステータス照会もありません。サイトが通知を受信できない場合は、ECPay の管理画面で決済を確認してください。
注文
注文ステータス
Pending payment: 購入者は ECPay に送られましたが、まだ支払っていない、または通知がまだ届いていません。
On hold, waiting for payment: 購入者は ATM、CVS、Barcode を選択し、支払いの詳細を受け取りました。注文メモには、銀行コードと仮想口座、払込番号またはバーコード、期限が表示されます。
Processing: 決済が確認されました（WooCommerce のデフォルト。バーチャルかつダウンロード可能な商品のみの注文は「完了」になります）。注文メモには ECPay の TradeNo、決済タイプ、金額、取引番号が表示されます。取引 ID は ECPay の TradeNo です。
On hold after payment: ECPay が注文と異なる金額または通貨を報告した場合、本番モードに切り替えた後にサンドボックス決済が届いた場合（実際の代金は回収されていません）、または注文がキャンセルされた後に決済が届いた場合です。注文メモに理由が説明されています。ECPay の管理画面と比較し、手動で注文を完了または返金してください。
Failed: ECPay が直近の決済試行が失敗したことを報告しました。メモには ECPay の戻りコードとメッセージが表示されます。購入者は再度試すことができます。
重複した通知は無視されます。支払済み・キャンセル済み・返金済みの注文が古い通知によって再度開かれることはありません。すでに支払済みの注文に対する 2 回目の決済（たとえば 2 つのブラウザタブから）は注文メモとして記録され、ECPay の管理画面で返金できます。ECPay の管理画面から開始されたシミュレーション決済は記録されるだけで、注文を支払済みにすることはありません。これは ECPay がこれらの決済の代金を回収しないためです。
返金
WooCommerce からの返金はできません。ECPay の管理画面で決済を返金し、その後 WooCommerce に手動で返金を記録してください。
ライセンスキー
本プラグインは vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > ECPay (綠界) の上部にあります。キーを License key に貼り付けて Activate をクリックします。この欄には、ライセンスの有効期限やドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの使用枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、ECPay はチェックアウト時に購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログインしているストア管理者には、(unlicensed — visible to admins only) と表示されたままこの決済方法が見え続けるため、キーを購入する前にプラグインを設定・テストできます。プラグインページと WooCommerce のページにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済はそのまま確認されます。
ライセンスが期限切れになっても、プラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
ECPay がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、ストアの通貨が TWD であること、本番モードで Merchant ID、Hash Key、Hash IV が設定されていることを確認してください。設定ページには、これらのいずれの場合もエラーが表示されます。
決済は完了したが、注文が「支払い待ち」のまま: ECPay の通知がストアのサイトに届いていません（サイトのダウン、ファイアウォール、メンテナンスモード、Basic 認証）。ECPay は数回再試行します。ECPay の管理画面で取引を確認し、注文を手動で完了することもできます。Enable Logging をオンにすると、プラグインが受信した通知を確認できます。
通知が 0|CheckMacValue verification failed を返す: Hash Key または Hash IV がストアの ECPay アカウントと一致していません。ECPay の管理画面から再度コピーしてください。
通知が 0|MerchantID mismatch を返す: 通知が、決済を開始した加盟店とは異なる ECPay 加盟店のものです。
通知が 0|Order not found を返す: 取引番号がこのストアによって発行されたものではありません。複数のショップが 1 つの ECPay アカウントを共有している場合などに起こります。各ショップに独自の Order Prefix を設定してください。
購入者に The order total is too small for ECPay. と表示される: 四捨五入後の注文合計が 1 TWD 未満になっており、ECPay で支払うことができません。
注文が金額の不一致のメモとともに「保留中」になっている: ECPay が報告した金額が注文合計と異なります。たとえば、購入者が支払いを開始した後に注文が編集された場合などです。ECPay の管理画面と比較し、手動で注文を完了または返金してください。
注文がサンドボックス決済の後で「保留中」になっている: 決済はテストモードで行われましたが、ストアは現在本番モードになっています。実際の代金は回収されていません。注文を手動で確認してください。
購入者に Too many payment attempts for this order と表示される: 注文が 30 回の決済試行に達しました。購入者に新しい注文をお願いしてください。
ライセンス欄にエラーが表示される: 欄内のメッセージに従ってください。たとえば、キーが別のドメインで既に使用されている場合は、vibefox.net のアカウントで枠を解放してから Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効化してください。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。
アンインストール
プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。本プラグインのライセンスキーとライセンスステータスは常に削除されます。設定、注文に保存された ECPay のデータ、ログは、Delete Data on Uninstall がオンになっていた場合のみ削除されます。そうでない場合は、後で再インストールするために残ります。既存の注文は決済メモと取引 ID を保持します。
ECPay は、それぞれの所有者の商標です。このプラグインは ECPay と提携しておらず、ECPay による推奨も受けていません。