VibeFox Worldline for WooCommerce — ヘルプ
要件
WordPress: 6.0 以降。
WooCommerce: 7.0 以降。インストールされ、有効になっていること。WooCommerce がない場合、本プラグインは有効化できません。
PHP: 8.0 以降。
Worldline アカウント: Worldline Direct（旧 Ingenico Direct）の加盟店アカウント。テストアカウントとライブアカウントは別々で、認証情報も異なります。各アカウントには、加盟店 ID（PSPID）、API Key ID とその Secret API Key、Webhook キーとその Secret が必要です。これらはすべて Worldline Merchant Portal で作成します（「Configuration」を参照）。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_worldline_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます。WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage に進むか、プラグイン一覧ページのプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. テスト用の認証情報を入力し、設定を保存して Test credentials をクリックします。
6. テストアカウントの Merchant Portal で Webhook URL を追加し、Webhook キーと Secret を入力します（「Configuration」を参照）。
7. Enable/Disable を有効にして、テスト決済を行います。その後、ライブ用の認証情報を入力し、ライブアカウントで Webhook の設定を繰り返し、Live credentials をクリックして Test Mode のチェックを外します。
Configuration
すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Worldline (Ingenico)。決済方法の一覧では、現在のモードに加盟店 ID、API Key ID、Secret API Key が揃うまで、Worldline は「設定が必要」と表示されます。設定ページでは、使用していないモードの認証情報欄がグレー表示になります。
General
Enable/Disable: Enable Worldline Gateway で決済方法のオン／オフを切り替えます。デフォルト：オフ。
Title: チェックアウト時に購入者に表示される決済方法の名称です。デフォルト：Worldline。
Description: チェックアウト時に決済方法の下に表示されるテキストです。デフォルト：Pay securely via Worldline.
Worldline Direct API
テストアカウントとライブアカウントの両方について、Worldline Merchant Portal で認証情報を取得します。PSPID が加盟店 ID です。Developer > Payment API で API Key ID と Secret API Key を作成し、Developer > Webhooks で Webhook キーと Secret を作成します。このセクションには、両方のポータルと Worldline のドキュメントへのリンクがあります。
Test Mode: Enable test mode (pre-production environment, no real money) をオンにすると、API のエンドポイントと認証情報の両方が切り替わります。テストモードでは事前本番環境とテスト用認証情報を使用し、ライブモードでは本番環境とライブ用認証情報を使用します。デフォルト：オン。実際の決済を受け付けるには、チェックを外します。テストモードがオンの間、購入者には決済方法の下に Test mode — no real money is charged. と表示されます。
テストアカウント（事前本番）
Test Merchant ID (PSPID): テストアカウントの PSPID です。
Test API Key ID: テストアカウントの Developer > Payment API で作成した API Key ID です。
Test Secret API Key: その API Key ID に対応する Secret API Key です。
Test Webhook Key ID: 任意です。設定すると、このキーで送信された Webhook のみが受け付けられます。
Test Webhook Secret: テストアカウントの Webhook Secret です。各 Webhook の署名を検証するために使用されます。
ライブアカウント（本番）
Live Merchant ID (PSPID): ライブアカウントの PSPID です。
Live API Key ID: ライブアカウントの Developer > Payment API で作成した API Key ID です。
Live Secret API Key: その API Key ID に対応する Secret API Key です。
Live Webhook Key ID: 任意です。設定すると、このキーで送信された Webhook のみが受け付けられます。
Live Webhook Secret: ライブアカウントの Webhook Secret です。
認証情報の確認
Test credentials と Live credentials のボタンは、各アカウントに保存された認証情報を Worldline へのテスト呼び出しによって確認します。先に変更を保存してください。結果はボタンの横に表示されます。例：Test credentials: connection successful.、API credentials are not configured.、または Worldline から返されたエラー。
Webhooks
Webhook は、購入者がストアに戻らない場合でも決済の情報をストアに通知します。たとえば、ブラウザを閉じた後や、決済が後から確認された場合です。テストアカウントの Merchant Portal で Developer > Webhooks を開き、設定のこのセクションに表示されているエンドポイント URL を追加します。URL は次のような形式です：https://your-site/wc-api/wlg_worldline_webhook/。設定に表示されている URL をそのまま正確にコピーしてください。リダイレクトなしで応答する必要があるため、言語プレフィックスや、www や https への強制リダイレクトを確認してください。次に、Webhook キー ID と Secret を Test Webhook Key ID と Test Webhook Secret に入力します。ライブアカウントでも、ライブ用の欄に同じ内容を入力してください。
プラグインは、Worldline のエンドポイント検証リクエストに自動的に応答します。決済イベント（決済ステータスの変更）と返金イベント（返金ステータスの変更）を処理します。その他のイベントは受け付けられますが、無視されます。有効な署名のない Webhook は拒否されます。Secret を署名したアカウントの加盟店 ID と異なる加盟店 ID から届いた Webhook も無視されます。Webhook がない場合、注文は購入者が決済後にストアへ戻ったときにのみ確定されます。
決済ページと注文
Payment page template: Merchant Portal にアップロードしたホステッドチェックアウトのテンプレート（バリアント）の名前です。任意です。例：SimplifiedCustomPaymentPage。空欄の場合は Worldline の標準決済ページが使用されます。
Order Status After Payment: Worldline が capture 済みの決済を確認した後の注文ステータスです。ステータスは即座に設定され、2 回目のステータス変更は行われません。決済は常に直接販売（承認と capture）として要求されます。
Logging: Enable debug logging は、すべての API リクエストと Webhook を WooCommerce > Status > Logs に、ソース wcp_worldline_gateway で書き込みます。エラーと警告は、この設定がオフでも常に記録されます。キー、カード情報、個人情報はマスクされます。デフォルト：オフ。
Delete Data: Delete the plugin settings and logs when the plugin is deleted。プラグインを無効化しても何も削除されません。注文に保存された決済データは、返金に必要なため保持されます。デフォルト：オフ。
バージョン 1.0 からアップデートする場合、従来の単一の認証情報セットは、ストアが使用していたモードに応じてテスト用またはライブ用の欄に移行されます。
チェックアウト
購入者は決済方法（デフォルトは Worldline）を選択し、注文を確定します。プラグインは、注文金額を注文通貨で指定した Worldline のホステッドチェックアウトを作成し、購入者を Worldline の決済ページに移動させます。そこで購入者は、カード、ウォレット、または貴社の Worldline アカウントで有効になっている他の決済方法で支払います。請求先の氏名、住所、メールアドレス、電話番号は Worldline に渡され、Worldline が対応している場合は、ストアの言語で決済ページが開きます。各決済の試行には、注文 ID とランダムな部分から成る独自の参照番号が割り当てられます。
支払い後、購入者はストアに戻ります。プラグインは、戻りを保存された試行と照合し、サーバー側で Worldline から決済ステータスを読み取ります。注文は、Worldline がこのステータス確認または署名付き Webhook によって確認した後にのみ、支払い済みとしてマークされます。その後、購入者には注文受付ページが表示されます。
決済が完了しなかった場合、購入者はメッセージとともに Pay for order ページに移動します：
購入者は、未払いの注文を Pay for order ページから再度支払うことができます。直前の試行がその間に支払い済みになっていた場合、購入者は注文受付ページに直接進み、二重に請求されることはありません。直前の決済ページが同じ金額・モードで開いたままで、作成から 30 分未満の場合は、購入者はそのページに戻されます。
Worldline が決済を開始できない場合、購入者には Payment error: Could not create checkout session. Please try again. が表示され、別の決済方法を選ぶことができます。理由は注文メモとログに追加されます。現在のモードの認証情報が不足している場合、購入者には This payment method is not available at the moment. Please choose another payment method. が表示されます。
この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。
プラグインは、単発の決済を Worldline のページでの直接販売として受け付けます。保存済みカードやトークン化、サブスクリプション、埋め込み型カードフォーム、WooCommerce からのキャプチャまたはキャンセルを伴う承認のみのモード、サーチャージ、Webhook の自動登録には対応していません。
注文と返金
Order statuses
Pending payment: 購入者は Worldline に移動しましたが、まだ支払っていないか、Worldline がまだ決済を確認していません。メモには、ホステッドチェックアウト ID、参照番号、モード（テストまたはライブ）が表示されます。
Processing or Completed: 決済は capture されました。ステータスは Order Status After Payment に従います。注文メモには、金額、Worldline の決済 ID、確認方法（署名付き Webhook またはステータス確認）が表示されます。注文のトランザクション ID は Worldline の決済 ID です。
On hold, waiting for capture: Worldline は決済を承認済み、または capture が要求済みと報告していますが、まだ capture されていません。注文メモにその内容が説明されています。Webhook が capture を確認すると、注文は自動的に支払い済みとしてマークされます。メモに決済が capture されていないと記載されている場合は、Worldline Merchant Portal で capture してください。
On hold, held for manual review: 決済が注文と一致しません。たとえば、金額または通貨が異なる（決済の開始後に注文が編集された）場合や、決済が別の試行に属している場合です。メモには、支払われた金額、注文合計、参照番号が表示されます。注文を確認して処理するか、決済を返金してください。
Failed: Worldline が最新の試行の決済を拒否またはキャンセルしたか、購入者が選択された決済方法の対象外でした。
Cancelled: 注文は貴社によって、または WooCommerce の在庫保持タイムアウトによってキャンセルされました。キャンセルまたは返金済みの注文に決済が届いた場合、注文は再開されません。メモでは、Worldline Merchant Portal で決済を返金またはキャンセルするか、注文を手動で復元するよう求められます。戻ってきた購入者には Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. と表示されます。
既に支払い済みの注文に 2 回目の決済が届いた場合、注文は再び変更されません。メモでは、Worldline Merchant Portal で 2 回目の決済を返金するよう求められます。
返金
注文を開き、Refund をクリックして金額を入力し、Refund via Worldline (Ingenico) をクリックします。全額返金と一部返金に対応しています。決済は capture 済みである必要があります。返金は常に、元の決済の環境（テストまたはライブ）に、そのアカウントの認証情報を使って送信されます。そのため、認証情報が設定されている必要があります。タイムアウト後に再試行された返金は、二重には実行されません。Worldline が返金を拒否した場合、WooCommerce にエラーが表示され、返金は記録されません。承認された返金は、Worldline の返金 ID とステータスとともに注文メモに追加されます。
Worldline からの返金ステータスの変更は Webhook で届き、注文メモに追加されます。Merchant Portal で行われた返金は、WooCommerce の返金として自動的には記録されません。必要に応じて、Refund via Worldline (Ingenico) を使わずに WooCommerce で手動返金を作成してください。
ライセンスキー
プラグインは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Worldline (Ingenico) の上部にあります。License key にキーを貼り付け、Activate をクリックします。ブロックには、ライセンスの有効期限日や貴社のドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Worldline はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. が表示されます。ログイン中のストア管理者には、決済方法が (unlicensed — visible to admins only) と表示されて引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインページと WooCommerce のページには、リマインダーが表示されます。既存の注文には影響しません。既に開始された決済は引き続き確認され、返金も機能します。
ライセンスの期限が切れても、プラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
Worldline がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに加盟店 ID、API Key ID、Secret API Key があることを確認してください。テストモードではテスト用の欄、ライブモードではライブ用の欄です。これらが不足している場合、決済の一覧では決済方法が「設定が必要」と表示されます。
決済は完了したが、注文が Pending payment のまま: Webhook が機能していません。使用しているアカウント（テストまたはライブ）の Merchant Portal で、エンドポイントが存在すること、その URL が設定に表示されたものと正確に一致しリダイレクトがないことを確認してください。そのアカウントの Webhook Secret が対応する欄（Test Webhook Secret または Live Webhook Secret）に入っていること、Webhook Key ID が空であるかキーと一致していることを確認してください。購入者が決済後にストアに戻ると、注文も確認されます。
Webhook が Webhook secret not configured と応答する: Webhook Secret が設定されていません。設定に Webhook Secret を入力してください。Worldline は Webhook を再試行します。
Webhook が Invalid signature と応答する: Webhook Secret が別のアカウントまたは別のキーのものである、または Webhook Key ID が Webhook を送信したキーと一致しません。
Webhook が Missing signature、Empty body、Invalid JSON と応答する: リクエストが予期された形式で Worldline から届いていない、またはプロキシやリダイレクトによって変更されました。URL がリダイレクトなしで応答するか確認してください。
Webhook が Ignored と応答する: Webhook が、そのモードの設定にある加盟店 ID とは異なる加盟店 ID から届きました。Test Merchant ID (PSPID) または Live Merchant ID (PSPID) を確認してください。
Webhook が Retry later と応答する: 同じ時刻に別のリクエストによって注文が更新されていました。Worldline は Webhook を再試行します。
Test credentials または Live credentials にエラーが表示される: まず設定を保存してから、Merchant ID、API Key ID、Secret API Key が同じアカウントのものであること、テスト用の値がテスト用の欄に、ライブ用の値がライブ用の欄に入っていることを確認してください。
購入者が注文時にエラーを見る: 注文メモ、または WooCommerce > Status > Logs（ソース wcp_worldline_gateway）を開いてください。デバッグログがオフの場合でも、エラーは記録されます。リクエストの詳細をすべて確認するには、Logging をオンにしてから再度お試しください。
テストの決済がライブの注文を確認しない: テストとライブは分けて管理されます。テスト用の Secret で署名された Webhook が、ライブの決済試行を確認することはなく、その逆も同様です。Test Mode を使用したいモードに切り替え、そのアカウントの認証情報と Webhook を使用してください。
決済後に注文が On hold になる: 注文メモを確認してください。Worldline がまだ capture を確認していない（Webhook が注文を完了させる）か、支払われた金額または通貨が注文と異なっていたかのいずれかです。
返金が環境に関するメッセージで失敗する: 決済はテストまたはライブの環境で行われましたが、その環境の認証情報が設定されていません。認証情報を入力して、再度お試しください。
開発者向け: フィルター wlg_hosted_checkout_data は、ホステッドチェックアウトのリクエストを変更します。たとえば、表示する決済方法を制限する場合に使います。wlg_gateway_icon は、決済方法のアイコンを変更します。
ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。たとえば、キーが別のドメインで既に使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして、新しいドメインでキーを有効化してください。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作を続けます。
アンインストール
プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定とログは、Delete Data がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。注文に保存された Worldline の決済データは、返金に必要なため、常に保持されます。既存の注文は、決済メモとトランザクション ID を保持します。
Worldline は、それぞれの所有者の商標です。本プラグインは Worldline と提携しておらず、Worldline による推奨もありません。