VibeFox Comgate for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 ～ 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールのインストールができません。

HTTPS: Comgate がバックグラウンド通知を送信できるように、ショップはインターネットから HTTPS でアクセスできる必要があります。

通貨: CZK、EUR、PLN、HUF、USD、GBP、RON、HRK、NOK、SEK。これら以外の通貨、または Comgate の最低金額を下回る合計金額の場合、支払い方法は表示されません。HUF の支払いは、Comgate の要件に従って整数のフォリントに丸められます。

Comgate アカウント: Comgate のクライアントポータルで、ショップ接続の Merchant ID と Secret（バックグラウンド通信用のパスワード）が必要です。また、そこで通知 URL を設定しておく必要があります（設定の項目を参照）。Comgate はテスト支払いと本番支払いで同じ Merchant ID と Secret を使用します。

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

インストール

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

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

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

4. Comgate のクライアントポータルで確認した Merchant ID と Secret を入力し、そこで通知 URL を設定します（設定の項目を参照）。

5. Enable / Disable をオンにして Save をクリックします。テスト支払いを行う場合は Test Mode をオンのままにし、その後オフにします。

インストール時に、モジュールは注文ステータス Comgate payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対応する新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Comgate Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。入力欄の上部では、Comgate が有効なのに Merchant ID または Secret が未入力の場合（その場合は両方が入力されるまで、チェックアウトで支払い方法が非表示になります）や、ショップの既定の通貨が Comgate に対応していない場合に警告が表示されます。テストモードがオンの間は、Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live. と表示されます。

Comgate

Enable / Disable: Enable Comgate Payment Gateway で支払い方法のオン／オフを切り替えます。Default: off。

Title: チェックアウトで購入者に表示される支払い方法の名前です。注文にも支払い方法名として保存されます。Default: Comgate。必須。

Description: チェックアウトで支払い方法の下に表示されるテキストです。Default: Pay securely via Comgate — cards, bank transfers, wallets and more。テストモードでは、これに TEST MODE: no real money is charged. が追加されます。説明が空の場合は、この文言だけが表示されます。

Comgate 接続

Comgate のクライアントポータルの Integration > shop connection settings から、ショップ識別子（Merchant ID）とパスワード（Secret）を取得します。同じ場所で、URL for passing the payment result（バックグラウンド通知）を、このセクションの Notification URL に表示されている URL に設定します。フレンドリー URL を使用している場合、その形式は https://your-shop/module/wcp_comgate_gateway/webhook のようになり、/en/ のような言語コードが含まれることもあります。URL は設定に表示されているとおりに正確にコピーしてください。Comgate は支払いのたびにこの URL を呼び出します。モジュールはその後、何かを変更する前に Comgate ステータス API で支払いを再確認します。購入者向けの戻り URL は、支払いごとに送信されます。ポータルで戻り URL（支払い済み、キャンセル、保留中）も求められる場合は、このセクションに表示される 2 つ目の URL を使用してください。この URL は return?id=${id}&refId=${refId} で終わります。

Merchant ID: Comgate のショップ識別子（加盟店）です。

Secret: このショップ接続のバックグラウンド通信用パスワード（Secret）です。保存済みの Secret は二度と表示されません。入力欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

保存済みの Secret を消去: チェックを入れて Save をクリックすると、保存済みの Secret が削除されます。入力欄が空の場合は、保存済みの値が維持されます。

Test Mode: テスト支払いを作成します（料金は請求されません）。Comgate はテスト支払いと本番支払いで同じ Merchant ID と Secret を使用します。テスト支払いには test=true が付きます。返金は常に元の支払いのモードで送信されます。Default: on。

決済ページ

Payment Methods: 購入者が選択できる Comgate の支払い方法です。Comgate でショップ向けに有効になっている方法のみが表示されます。

Language: Comgate 決済ページの言語です。Automatic (shop language, English as fallback)（既定）または 26 言語のいずれかを選択できます。

注文

Order Status After Payment: Comgate が支払いを確認したときに設定されるステータスです。

注文と一致しない支払い、本番モードでのテスト支払い、事前承認された支払いは、常に Comgate payment on hold になります。

詳細設定

Debug Log: API リクエストと通知を、モジュールフォルダ内の logs/comgate_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。シークレットと個人情報は記録されません。エラーは常に記録されます。Default: off。

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

Delete Data on Uninstall: オンの場合、モジュールをアンインストールするとゲートウェイの設定とログが削除されます。注文と Comgate の取引 ID は常に保持されます。Default: off。

チェックアウト

支払いの段階で、購入者は支払い方法（既定では Comgate）を選択し、注文を確定します。モジュールは、カートの合計金額をカートの通貨で Comgate に対して支払いとして作成し、購入者を Comgate の決済ページにリダイレクトします。購入者のメールアドレスと氏名は Comgate に渡され、支払いには Cart とカート番号のラベルが付きます。有効なメールアドレスが必要です。Comgate のページで、購入者はあなたが許可した支払い方法のいずれかで支払います。この時点では、まだ注文は存在しません。

支払いの後、購入者はショップに戻ります。注文は、Comgate が確認した後にのみ支払い済みとしてマークされます。モジュールは、バックグラウンド通知が届いたときと購入者が戻ったときの両方で、Comgate ステータス API から支払いを読み取ります。その後注文が作成され、購入者には標準の注文確認ページが表示されます。注文が保留にされた場合、ページには Your payment is being reviewed. We will contact you if anything else is needed. が追加されます。事前承認された注文が後からキャンセルされた場合は、ページに Your Comgate payment was not completed. Please contact us about this order. と表示されます。

購入者が戻った時点でまだ支払いが確認されていない場合（例：銀行振込の処理中）、Payment confirmation ページに Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. と表示され、Check again ボタンと Back to checkout ボタンがあります。

支払いがキャンセルされたか期限切れになった場合、購入者は The Comgate payment was cancelled or has expired. You can try again or choose another payment method. と表示されたチェックアウトに戻ります。カートは保持されます。新しい試行のたびに、前回の試行が先に確認されるため、すでに完了した支払いに二重請求が発生することはありません。前回の試行が未完了のままであれば、Comgate で取り消されます。古い試行の遅延した支払いについては、注文が作成されます。

Comgate が支払いを開始できなかった場合、購入者はチェックアウトに留まり、The Comgate payment could not be started. Please try again or choose another payment method. などの短いメッセージが表示されます。これは、Comgate がこの金額または通貨を受け付けられないこと、または選択した Comgate の支払い方法が利用できないことを示します。技術的な理由はログに記録されます。

通知は、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。

このモジュールは、Comgate のページでの一回限りの支払いのみに対応しています。定期払い、サブスクリプション、カードの保存には対応しておらず、埋め込み型の Comgate チェックアウト、お使いのサイト上の Apple Pay や Google Pay のボタン（これらは Comgate のページで利用できます）、PrestaShop からの事前承認の売上計上やキャンセルもありません。通知がない場合、支払いステータスは自動的に確認されず、購入者が戻ったときにのみ確認されます。

注文と返金

注文ステータス

まだ注文はありません: 購入者は Comgate に送られ、まだ支払いをしていないか、Comgate が支払いを保留中と報告しています。存在するのはカートのみです。

Payment accepted or Delivered: Comgate が、同じ金額と通貨で支払いを PAID と報告しました。ステータスは Order Status After Payment に従います。支払いは Comgate の取引 ID とともに記録されます。テスト支払いには Comgate test payment — no money was charged. の備考が付きます。

Comgate payment on hold: 支払われた金額または通貨が注文と異なる、ショップが本番モードのときにテスト支払いが確認された（入金はありません）、または支払いが事前承認のみである（Comgate アカウントでの事前承認）のいずれかです。事前承認された支払いは、Comgate ポータルで売上計上を行うと自動的に支払い済みになります。備考に理由が記載されます。

Canceled: 事前承認された支払いが Comgate でキャンセルされたか、期限切れになりました。その後 Comgate が支払いを確認した場合、注文は支払い済みとして再度開かれ、出荷前に在庫を確認するよう求める備考が付きます。

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

すでに支払い済みの注文について、Comgate が別の PAID の支払いを報告した場合、注文は変更されません。備考で、Comgate ポータルで確認し、重複分を返金するよう求められます。再送された確認によって、返金済みの注文が再び有効になることはありません。

Comgate 支払いブロック

注文ページには Comgate payment ブロックが表示され、取引 ID、Comgate ステータス、支払い金額、注文合計、返金済み金額、テスト支払いの場合の Test mode バッジ、確認が必要な理由、返金履歴、注文の Comgate notes が含まれます。

返金

Comgate payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Comgate をクリックします。Refund this amount through Comgate? This cannot be undone. という確認に同意してください。全額返金と部分返金に対応しています。注文を編集する権限が必要です。Modules のページへのアクセス権は必要ありません。返金は支払い済みの Comgate 取引に対して行われ、元の支払いのモード（テストまたは本番）で送信されます。Comgate は PAID の支払いのみを返金し、返金額は支払い済みの金額を超えられません。HUF の返金は整数のフォリントである必要があります。Comgate が返金を受け付けなかった場合、ブロックにエラーが表示され、返金は記録されません。返金が成功すると、金額、Comgate 取引、理由とともに返金履歴と備考に追加されます。全額返金を行うと、注文は Refunded になります。部分返金ではステータスは変わりません。

返金は支払い済みの注文に対してのみ利用できます。金額または通貨の不一致により保留になった注文は、PrestaShop から返金できません。Comgate ポータルで返金してください。このモジュールはクレジットメモを作成しません。注文ページの PrestaShop 標準の返金ボタンでは、Comgate を経由して返金は行われません。Comgate ポータルで行われた返金は、ショップに報告されません。

ライセンスキー

このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Comgate Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Comgate Gateway > Configure ページの最上部、設定より上にあります。キーを License key に貼り付けて Activate をクリックしてください。その後、ブロックにはキーが伏せ字で表示され、ステータス（ライセンスの有効期限日、ドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-comgate の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに Comgate が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、Merchant ID と Secret が入力されていること、カートの通貨がサポートされていること、注文合計が Comgate の最低金額（例：1 CZK、0.10 EUR、100 HUF）を下回っていないことを確認してください。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているかも確認してください。

支払いは完了したが、注文が作成されていない: Comgate がバックグラウンド通知を配信できていません。Comgate ポータルの URL for passing the payment result（設定の Notification URL と完全に一致している必要があります）、ショップがインターネットから HTTPS でアクセスできること、ログを確認してください（Debug Log をオンにします）。Comgate は配信されなかった通知を再送します。モジュールは通知を処理できなかった場合は毎回エラーで応答するため、通知は再試行されます。購入者がショップに戻った際にも注文は作成されます。

通知の応答が Invalid merchant or secret: 設定の Merchant ID または Secret が、Comgate ポータルのショップ接続と一致していません。

通知の応答が Gateway not configured: 設定の Merchant ID または Secret が空です。入力されると Comgate が再試行します。

通知の応答が Unknown transaction、Order not found、Reference mismatch: この通知は、このショップがそのカートのために作成したものではない支払いに関連しています。何も変更されません。

通知の応答が Status verification failed、Status verification rejected、Busy, retry later: Comgate ステータス API に接続できなかった、リクエストが拒否された、または同じ瞬間に別のリクエストがそのカートを処理していた、のいずれかです。注文を作成できなかった場合も Busy が返されます。理由はログに記録されています。Comgate は通知を再試行します。

ブラウザで通知 URL に code=1&message=POST%20required と表示される: これは正常です。この URL は Comgate からのリクエストのみを受け付けます。

購入者に We could not verify the Comgate payment と表示される: 戻りリンクがカートと一致しませんでした。料金が請求されていた場合でも、通知によって注文は作成されます。購入者が再度支払う前に、Comgate ポータルで支払いを確認してください。

購入者に The order total is below the minimum amount accepted by Comgate、または A valid billing e-mail address is required for Comgate payments と表示される: このカートは現状のままでは Comgate で支払うことができません。

支払い後に注文が Comgate payment on hold になる: Comgate payment ブロックの備考を確認してください。支払われた金額または通貨が異なっていた、本番モードでテスト支払いが届いた、または支払いが事前承認のみだった、のいずれかです。Comgate ポータルで支払いを確認し、注文を手動で完了するか返金してください。

返金に失敗する: ブロックに表示されたメッセージを確認してください。Comgate rejected the refund: the amount exceeds the refundable amount. は、金額が返金可能な残額を超えていることを意味します。PAID 以外のステータスの支払いは返金できません。Comgate could not be reached. The refund was not made — please try again later. は接続の問題を意味します。

アンインストール

Modules > Module Manager に移動し、VibeFox Comgate Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Comgate の取引と返金、および注文ステータス Comgate payment on hold は常に保持されるため、以前に支払い済みの注文は、再インストール後も返金できます。既存の注文は、支払いの備考と取引 ID をそのまま保持します。

Comgate は、各所有者の商標です。このモジュールは Comgate と提携しておらず、Comgate による推奨もされていません。