VibeFox Worldline for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。本モジュールは、それより古い PHP バージョンではインストールされません。

Worldline アカウント: Worldline Direct（旧 Ingenico Direct）の加盟店アカウント。テストアカウントと本番アカウントは別々で、認証情報も異なります。アカウントごとに、加盟店 ID（PSPID）、API Key ID とその Secret API Key、Webhook キーとその secret が必要です。これらはすべて Worldline Merchant Portal で作成します（設定を参照）。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ有効です。

インストール

1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックします。後から行う場合は、モジュール一覧で VibeFox Worldline Gateway を探して Configure をクリックします。

3. VibeFox ライセンスキーを、Configure ページ上部のライセンスブロックの License key に貼り付け、Activate をクリックします（ライセンスキーを参照）。

4. テスト用の認証情報を入力し、Save をクリックしてから Test credentials をクリックします。

5. テストアカウントの Merchant Portal で Webhook URL を追加し、Webhook キーと secret を入力します（設定を参照）。

6. Enable/Disable を有効にして、テスト支払いを行います。その後、本番用の認証情報を入力し、本番アカウントでも Webhook の設定を繰り返して、Live credentials をクリックし、Test Mode を無効にします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting Worldline capture と Worldline payment on hold を作成します。PrestaShop は、その時点で有効な国に対して新しい決済モジュールを有効にします。通貨、国、顧客グループは Payment > Preferences で確認し、後から追加する国はそこでチェックしてください。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Worldline Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。項目の上部には、現在のモードの認証情報（Merchant ID、API Key ID、Secret API Key）が不完全な場合に警告が表示されます。その場合、チェックアウトで決済方法が非表示になるためです。テストモードが有効な間は、Test mode is on (pre-production environment): no real money is charged. と表示されます。

Worldline (Ingenico)

Enable/Disable: Enable Worldline Gateway は決済方法を有効または無効にします。デフォルト: 無効。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも決済方法の名前として保存されます。デフォルト: Worldline。必須。

Description: チェックアウトで決済方法の下に表示されるテキストです。デフォルト: Pay securely via Worldline.

Worldline Direct API

認証情報は、テストアカウントと本番アカウントの Worldline Merchant Portal で取得します。PSPID が Merchant ID です。Developer > Payment API で API Key ID と Secret API Key を作成し、Developer > Webhooks で Webhook キーと secret を作成します。このセクションには、両方のポータルと Worldline のドキュメントへのリンクがあります。

Test Mode: 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 です。

保存済みの secret キーと Webhook secret は、以後表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secrets: secret にチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が維持されます。

Check credentials: Test credentials と Live credentials のボタンは、Worldline へのテスト呼び出しによって、各アカウントの保存済み認証情報を確認します。先に変更内容を保存してください。結果はページ上部に表示されます。例：Test credentials: connection successful.、API credentials are not configured.、または Worldline から返されたエラー。

Webhook

Webhook は、購入者がストアに戻らない場合（ブラウザを閉じた場合や、支払いが後で確認された場合など）でも、支払いについてストアに通知します。Merchant Portal で、テストアカウントの Developer > Webhooks を開き、このセクションの Endpoint URL に表示されている URL を追加します。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_worldline_gateway/webhook のような形になり、/en/ などの言語コードが付くこともあります。URL は設定画面に表示されているとおりに正確にコピーしてください。リダイレクトなしで応答する必要があります。次に、Webhook キー ID と secret を Test Webhook Key ID と Test Webhook Secret に入力します。本番アカウントでも、本番用の項目で同じ設定を行ってください。

モジュールは、Worldline からのエンドポイント検証リクエストに自動で応答します。支払いイベント（支払いステータスの変更）と返金イベント（返金ステータスの変更）を処理します。その他のイベントは受け付けられますが、無視されます。有効な署名のない Webhook は拒否されます。イベントは支払いが行われたアカウントの secret で署名されている必要があるため、テストの Webhook が本番の支払いを確定させることはありません。また、Webhook が、その secret で署名したアカウントとは異なる Merchant ID から送られてきた場合も無視されます。Webhook がない場合、注文は購入者が支払い後にストアに戻ったときにのみ作成されます。

決済ページと注文

Payment page template: Merchant Portal にアップロードされたホステッド決済ページのテンプレート（バリアント）の名前です。任意で、例：SimplifiedCustomPaymentPage。空欄のままにすると、Worldline のデフォルトページが使用されます。

Order Status After Payment: Worldline がキャプチャ済みの支払いを確認した後の注文ステータスです。支払いは常に直接販売（承認とキャプチャ）として要求されます。

承認済みの支払いは Awaiting Worldline capture で待機します。金額や通貨が一致しない場合は、常に Worldline payment on hold になります。

詳細設定

Logging: すべての API リクエストと Webhook を、モジュールフォルダ内の logs/wlg_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。エラーと警告は、この設定が無効でも常に記録されます。キー、カード情報、個人情報はマスクされます。デフォルト: 無効。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。

Delete Data: 有効にすると、モジュールをアンインストールしたときにモジュールの設定とログが削除されます。Worldline の取引と返金、およびモジュールの注文ステータスは常に残ります。既存の注文が返金のためにそれらを必要とするためです。デフォルト: 無効。

チェックアウト

支払いの段階で、購入者は決済方法（デフォルトは Worldline）を選んで確定します。モジュールは、カート金額をカートの通貨で Worldline のホステッド決済ページとして作成し、購入者を Worldline の決済ページへ送ります。そこで購入者は、カード、ウォレット、または貴社の Worldline アカウントで有効になっている他の決済方法で支払います。請求先の氏名、住所、メールアドレス、電話番号は Worldline に渡され、Worldline が対応している場合は決済ページが購入者の言語で開きます。支払いの試行ごとに、カート ID とランダムな部分からなる独自のリファレンスが付与されます。この時点ではまだ注文は存在しません。

支払い後、購入者はストアに戻ります。モジュールは、戻りを保存された試行と照合し、サーバー側で Worldline から支払いステータスを読み取ります。注文は、Worldline が確認した後にのみ支払い済みとしてマークされます。このステータス確認、または署名付きの Webhook によって確認されます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。ページには Your payment with Worldline has been received. と表示されます。支払いが承認済みでまだキャプチャされていない場合、ページには Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. と表示されます。そのような注文の支払いが後で失敗した場合、ページには Your Worldline payment was not completed. Please contact us about this order. と表示されます。

支払いが完了しなかった場合、注文は作成されず、カートは保持され、購入者はメッセージとともにチェックアウトに戻ります。

ステータスをまだ確認できない場合、Payment confirmation ページに We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. と表示され、Check again と Back to checkout のボタンが表示されます。Webhook が届くと、直ちに注文が作成されます。

購入者が同じカートで再度支払う場合、モジュールはまず前回の試行を確認します。その間に支払い済みになっていれば、購入者は直接注文確認ページに進み、二重に請求されることはありません。前回の決済ページが同じ金額と同じモードで開いたままで、作成から 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. と表示されます。

Webhook は、ストアがメンテナンスモードの間も機能し、ストアの国による制限ではブロックされません。

本モジュールは、Worldline のページでの単発の支払いを直接販売として受け付けます。保存済みカードやトークン化、サブスクリプション、埋め込み型カードフォーム、PrestaShop からのキャプチャまたはキャンセルを伴う承認のみのモード、サーチャージ、Webhook の自動登録には対応していません。

注文と返金

注文ステータス

No order yet: 購入者は Worldline に移動しましたが、まだ支払っていないか、Worldline がまだ支払いを確認していません。存在するのはカートだけです。

Payment accepted or Delivered: 支払いがキャプチャされました。ステータスは Order Status After Payment に従います。支払いは、Worldline の支払い ID を取引 ID として記録され、メモには金額、支払い ID、確認方法（署名付き Webhook またはステータス確認）が表示されます。

Awaiting Worldline capture: Worldline が、支払いを承認済み、またはキャプチャを要求済みと報告しましたが、まだキャプチャされていません。まだ支払いは記録されていません。Webhook がキャプチャを確認すると、注文は支払い済みのステータスに移ります。メモに支払いがキャプチャされていないと書かれている場合は、Worldline Merchant Portal でキャプチャしてください。

Worldline payment on hold: 支払いがカートと一致しません。たとえば、金額や通貨が異なる場合（支払いの開始後にカートが変更された場合）や、支払いが別の試行に属している場合です。メモには、支払われた金額、注文合計、リファレンスが表示されます。注文を確認して処理するか、支払いを返金してください。

Payment error: キャプチャを待っていた注文の支払いを、Worldline が拒否またはキャンセルしました。

Refunded: 支払いはモジュールを通じて全額返金されました。

キャンセル済みまたは返金済みの注文に対して支払いが届いた場合、注文は再開されません。メモでは、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 回目の支払いを返金するよう求められます。

Worldline 支払いブロック

注文ページには Worldline payment ブロックが表示され、支払い ID、加盟店リファレンス、ホステッド決済ページ、試行ステータス、請求額と返金額、テスト支払い用の Test environment バッジ、返金履歴、注文の Payment notes が含まれます。

返金

Worldline payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Worldline をクリックします。確認メッセージ Refund this amount through Worldline? This cannot be undone. で承認してください。全額返金と一部返金に対応しています。支払いはキャプチャ済みである必要があります。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は Worldline が請求した金額と通貨で行われるため、金額や通貨の不一致が起きた後は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。返金は常に、元の支払いと同じ環境（テストまたは本番）へ、そのアカウントの認証情報を使用して送信されるため、認証情報が設定されている必要があります。タイムアウト後に再試行された返金は二重に実行されず、1 つの注文で同時に実行されるのは 1 件の返金のみです。Worldline が返金を拒否した場合、ブロックにエラーが表示され、返金は記録されません。承認された返金は、Worldline の返金 ID とステータスとともに、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded に設定されます。一部返金ではステータスは変わりません。

本モジュールはクレジットスリップを作成しません。注文ページにある PrestaShop の標準の返金ボタンは、Worldline を通じて金額を返金しません。

Worldline からの返金ステータスの変更は Webhook で届き、返金履歴を更新し、メモに追加されます。Merchant Portal で行った返金は、注文ステータスを変更せず、クレジットスリップも作成しません。必要に応じて手動で更新してください。

ライセンスキー

本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Worldline Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Worldline Gateway > Configure の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後ブロックには、キーがマスクされた状態、ステータス（例：ライセンスの有効期限日とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-worldline の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、モジュールの Configure 権限を持つスタッフだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックは理由を表示します。例：Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付。ショップのアドレスを変更した後、またはアカウントでドメイン枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。

1 つのキーは 1 つのドメインでのみ有効です。メインショップのドメインで、マルチストア構成でも同じです。ショップからキーを削除しても、ドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、Worldline はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、あなたが管理画面にログインしていることを認識しないため、支払い方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認され、返金も機能します。

ライセンスが期限切れになっても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Worldline が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに Merchant ID、API Key ID、Secret API Key があることを確認してください。テストモードではテスト用の項目、本番モードでは本番用の項目です。不足していると設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されていることを確認してください。

支払いは完了したが、注文が作成されなかった: Webhook が機能していません。使用しているアカウント（テストまたは本番）の Merchant Portal で、エンドポイントが存在し、その URL が Endpoint URL に表示されているものと完全に一致していること（リダイレクトがないこと）を確認してください。そのアカウントの Webhook secret が対応する項目（Test Webhook Secret または Live Webhook Secret）に入っていること、Webhook キー ID の項目が空であるか、キーと一致していることを確認してください。注文は、購入者が支払い後にストアに戻った場合にも作成されます。

Webhook が Webhook secret not configured と応答する: Webhook secret がどちらも設定されていません。設定画面で Webhook secret を入力してください。Worldline は Webhook を再試行します。

Webhook が Invalid signature と応答する: Webhook secret が別のアカウントまたは別のキーのものである、あるいは Webhook キー ID が、Webhook を送信したキーと一致しません。テストと本番の secret が入れ替わっていないか確認してください。

Webhook が Missing signature、Empty body、または Invalid JSON と応答する: リクエストが期待された形式で Worldline から届いていないか、プロキシやリダイレクトによって変更されました。URL がリダイレクトなしで応答するか確認してください。

Webhook が Ignored と応答する: その Webhook は、そのモードの設定とは異なる Merchant ID から届きました。Test Merchant ID (PSPID) または Live Merchant ID (PSPID) を確認してください。

Webhook が Retry later と応答する: 同じ瞬間に別のリクエストで注文が確認されていたか、注文を作成できませんでした（例：モジュールが無効）。Worldline は Webhook を再試行します。理由は Log 欄で確認してください。

ブラウザで Webhook URL に Method not allowed と表示される: これは正常です。この URL は Worldline からのリクエストのみを受け付けます。

Test credentials または Live credentials にエラーが表示される: 先に設定を保存し、Merchant ID、API Key ID、Secret API Key が同じアカウントのものであること、テスト値がテスト用の項目に、本番値が本番用の項目に入っていることを確認してください。

購入者が Worldline を選択したときにエラーが表示される: モジュールのページにある Log 欄を確認してください。エラーは、Logging が無効でも記録されます。リクエストの詳細をすべて確認するには、Logging を有効にしてもう一度お試しください。

テスト支払いでは本番の支払いが確認されない: テストと本番は別々です。Test Mode を使用したいモードに切り替え、そのアカウントの認証情報と Webhook を使用してください。

支払い後に注文が Worldline payment on hold または Awaiting Worldline capture になっている: Worldline payment ブロックのメモを確認してください（注文ステータスを参照）。Worldline がまだキャプチャを確認していない（Webhook が注文を完了させる）か、支払われた金額または通貨がカートと異なっていたかのいずれかです。

返金が環境に関するメッセージで失敗する: 支払いはテスト環境または本番環境で行われており、その環境の認証情報が設定されていません。認証情報を入力して再度お試しください。

開発者向け: フック actionWlgHostedCheckoutData は、送信前にホステッド決済のリクエストを変更します。たとえば、表示される決済方法を制限するためなどに使用します。

アンインストール

Modules > Module Manager に移動し、VibeFox Worldline Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンス状態は常に削除されます。Delete Data が有効な場合、モジュールの設定とログが削除されます。無効な場合、後で再インストールできるようすべての設定が保持されます。Worldline の取引と返金、および注文ステータス Awaiting Worldline capture と Worldline payment on hold は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、支払いメモと取引 ID を保持します。

Worldline は、それぞれの所有者の商標です。本モジュールは Worldline と提携しておらず、Worldline による推奨も受けていません。