VibeFox PayMongo for PrestaShop — ヘルプ
動作要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。古い PHP バージョンではモジュールをインストールできません。
通貨：フィリピンペソ（PHP）。PayMongo は、PHP 建てのカートの場合にのみチェックアウトに表示されます。ストアの既定の通貨が PHP でない場合、設定ページに警告が表示され、購入者は PayMongo を表示するために PHP に切り替える必要があります。
PayMongo アカウント：PayMongo アカウントの API シークレットキーと、モードごとのウェブフックが必要です（設定を参照）。使用するのはシークレットキー（sk_test_...、sk_live_...）とウェブフックの署名シークレット（whsk_...）のみです。決済ページは PayMongo がホストするため、公開キーは不要です。提供する支払い方法は、PayMongo アカウントで有効になっている必要があります。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で確認する場合は、モジュール一覧から VibeFox PayMongo Payment Gateway を探し、Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. PayMongo のシークレットキーを貼り付け、PayMongo でウェブフックを作成し、その署名シークレットを貼り付けます（設定を参照）。
5. 支払い方法を選択し、Enable/Disable をオンにして Save をクリックします。Test mode をオンにして支払いをテストし、その後オフにします。
インストール時に、モジュールは二つの注文ステータス Awaiting PayMongo payment と PayMongo payment on hold を作成します。Payment > Preferences で、フィリピンペソ、購入者の国、顧客グループについてモジュールが許可されているか確認してください。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上では、ストアの既定の通貨が PHP でない場合、現在のモードにシークレットキーがない場合（この場合、PayMongo はチェックアウトに表示されません）、またはウェブフックの署名シークレットがない場合（この場合、支払いは購入者がストアに戻ったときにのみ確認されます）に、ページが警告を表示します。テストモードがオンの間は、Test mode is on: no real payments are made. も表示されます。
PayMongo
Enable/Disable: Enable PayMongo は支払い方法をオンまたはオフにします。既定値：オフ。
Title: 購入者がチェックアウトで目にする支払い方法の名称です。注文にも、この名称が保存されます。既定値：PayMongo (Card, GCash, GrabPay, Maya)。必須。
Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods: PayMongo の決済ページで提供される方法です。PayMongo アカウントで有効になっている方法だけを選択してください。そうしないと PayMongo がチェックアウトを拒否します。何も選択されない場合は既定値が使われます。既定値：Cards, GCash, GrabPay and Maya。
API キー
シークレットキーは PayMongo Dashboard > Developers > API keys からコピーします。公開キーは不要です。各キーは、想定されたプレフィックスで始まる必要があります。プレフィックスが誤っている値は保存されません。ページには、フィールド must start with にプレフィックスが必要であること、そして The previous value was kept. が表示されます。
Test mode: Enable test mode (no real payments). 新しい支払いはテストキーを使用します。以前に行われた支払いは、行われたモードを保持するため、ステータスの確認や返金では対応するキーが使われます。既定値：オン。実際の支払いを受け付けるにはオフにします。
Test secret key: テストモードのシークレットキーです。sk_test_ で始まります。
Test webhook secret: テストモードのウェブフックの署名シークレットです。whsk_ で始まります。
Live secret key: 本番モードのシークレットキーです。sk_live_ で始まります。
Live webhook secret: 本番モードのウェブフックの署名シークレットです。whsk_ で始まります。
保存されたキーとシークレットは、二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。
Clear saved secrets: キーまたはシークレットにチェックを入れて Save をクリックすると、削除されます。空のフィールドは、保存された値を維持します。
ウェブフック
ウェブフックは、購入者が支払い後にブラウザを閉じた場合でも、支払いが行われたことをストアに伝えます。テストモードと本番モードそれぞれについて、PayMongo ダッシュボード（または PayMongo API）で、このセクションの Webhook URL に表示される URL を指定してウェブフックを作成します。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_paymongo_payment_gateway/webhook のような形になり、/en/ のような言語コードが付くこともあります。URL は設定に表示されたとおりに正確にコピーしてください。
次のイベントを選択します（これらはこのセクションにも記載されています）：
各ウェブフックの署名シークレット（whsk_...）を、Test webhook secret または Live webhook secret にコピーします。有効な署名がないウェブフックは拒否されます。署名は、そのモードのシークレットで検証され、イベントのモードも一致している必要があります。そのため、テスト用のウェブフックが本番の支払いを確認することはありません。注文を作成または変更する前に、すべてのイベントは、支払いのモードのシークレットキーを使って PayMongo API で再度確認されます。PayMongo はアカウント全体のイベントをすべてのウェブフックに送信しますが、このストアで開始されていない支払いのイベントは無視されます。ウェブフックがない場合、注文は購入者が支払い後にストアに戻ったときにのみ作成されます。
注文
Order status after payment: 支払いが成功した後に設定される注文ステータスです。
処理中の支払いは Awaiting PayMongo payment で待機します。金額または通貨の不一致、および本番ストアでのテスト支払いは、常に PayMongo payment on hold になります。
詳細設定
Debug log: PayMongo API の呼び出しとウェブフックのイベントを、モジュールのフォルダ内にある logs/paymongo_p_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は、このスイッチがオフの場合でも常に記録されます。キーと購入者データは、決して記録されません。既定値：オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Delete data on uninstall: オンの場合、モジュールをアンインストールすると、設定とログが削除されます。注文に保存された PayMongo の ID、返金、およびモジュールの注文ステータスは、返金と会計処理に必要なため、常に保持されます。既定値：オフ。
チェックアウト
支払い手続きの段階で、購入者は支払い方法（既定では PayMongo (Card, GCash, GrabPay, Maya)）を選択し、その説明を確認します。テストモードでは、チェックアウトに Test mode: no real payment will be made. も表示されます。PayMongo が提供されるのは、合計金額が ₱100.00 以上の PHP 建てのカートの場合のみです。
確定すると、モジュールはカートの合計金額（PHP 建て）について PayMongo Checkout Session を作成します。Cart # とカート番号の行が一つ含まれ、購入者は PayMongo の決済ページに移動します。購入者の氏名、メールアドレス、電話番号、請求先住所は PayMongo に渡されます。そこで購入者は、選択された支払い方法の一つを選んで支払います。この時点では、まだ注文は存在しません。
支払い後、購入者はストアに戻ります。注文は、PayMongo が支払いを確認した後にのみ支払い済みとしてマークされます。購入者が戻ったときと、ウェブフックが届いたときに、モジュールは支払いについて PayMongo API に問い合わせます。その後、注文が作成され、購入者は Your PayMongo payment has been received. と表示された標準の注文確認ページを確認します。購入者が戻った時点で PayMongo がまだ支払いを処理している場合、注文は Awaiting PayMongo payment で作成され、ページには PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. が表示されます。その支払いが後で失敗した場合、ページには Your PayMongo payment was not completed. Please contact us about this order. が表示されます。購入者が戻った時点で PayMongo に接続できない場合は、購入者に再度支払わないよう求める Payment confirmation ページが表示され、Check again ボタンが表示されます。ウェブフックは届き次第、注文を作成します。
購入者が PayMongo のページでキャンセルしたり、支払いを完了しなかったりした場合、購入者はチェックアウトに戻り、You cancelled the PayMongo payment. You can try again or choose another payment method. または Your PayMongo payment was not completed. You can try again or choose another payment method. と表示されます。カートは保持されます。新しい試行では、まず前回の試行を確認します。その間に支払いが済んでいれば、新たな支払いなしで注文が作成されます。そうでなければ、前回の PayMongo 決済リンクは期限切れになり、カートを二重に支払うことはできません。前回の支払いがまだ処理中の間は、購入者に Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again. と表示されます。
PayMongo が支払いを開始できない場合、購入者はチェックアウトに留まり、短いメッセージが表示されます。たとえば The payment could not be started. Please try again or choose another payment method. や PayMongo could not be reached. Please try again in a moment. などです。技術的な理由はログに記録されます。
ウェブフックは、ストアがメンテナンスモードの間も動作し、ストアの国による制限でブロックされることもありません。
モジュールは、PayMongo のページでの一回払いのみを受け付けます。購入者自身のチェックアウトページにはカード入力欄がなく、カードの保存、サブスクリプションや定期払い、分割払い、オーソリとキャプチャの分離にも対応していません。
注文と返金
注文ステータス
No order yet: 購入者は PayMongo に移動しましたが、まだ支払っていないか、PayMongo がまだ支払いを確認していません。存在するのはカートだけです。
Payment accepted or Delivered: 支払いが確認されました。ステータスは Order status after payment に従います。支払いは、取引 ID として PayMongo の支払い ID（pay_...）と共に記録され、メモには支払い、金額、方法、モード、および確認方法（ウェブフックまたは戻り）が表示されます。
Awaiting PayMongo payment: 購入者は、PayMongo がまだ支払いを処理している間に戻りました。PayMongo が確認すると、注文は支払い済みのステータスに移ります。
PayMongo payment on hold: 支払われた金額または通貨がカートの合計と異なる場合（たとえば、支払いの開始後に別のタブでカートが変更された場合）、またはストアが本番モードの間にテストモードで支払いが行われた場合（その場合、お金は受け取られず、支払いも記録されません）、または注文がキャンセルされた後に支払いが届いた場合です。メモにその理由が説明されています。注文を確認して処理するか、支払いを返金してください。
Payment error: 署名付きの payment.failed ウェブフックにより、Awaiting PayMongo payment の注文の最新の支払い試行が失敗したことが報告されました。メモには PayMongo の失敗コードとメッセージが表示されます。同じ支払いが後で成功した場合、注文は支払い済みのステータスに移ります。
Refunded: モジュールを通じて、支払いが全額返金されました。
すでに支払い済みの注文に対して二回目の支払いが届いた場合（たとえば古いチェックアウトリンクを経由した場合）、注文は変更されません。メモには、重複した支払いを PayMongo ダッシュボードで返金するよう記載されます。支払い後にキャンセルまたは返金された注文が、再度開かれることはありません。
PayMongo payment ブロック
注文ページには PayMongo payment ブロックが表示されます。ここには、PayMongo の支払い ID と方法、payment intent、checkout、モード、ステータス、支払われた金額と返金された金額、テスト支払い用の Test mode バッジ、注文の PayMongo メモ、返金履歴が含まれます。
返金
PayMongo payment ブロックで金額を入力します（まだ返金されていない金額が自動で入ります）。必要に応じて理由を入力し、Refund via PayMongo をクリックします。確認の質問 Refund this amount through PayMongo? This cannot be undone. に応じてください。全額返金と一部返金に対応しており、小数点以下は最大二桁までです。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は、PayMongo が実際に請求した金額を上限としています。そのため、金額の不一致が発生した後は、注文合計ではなく、購入者が支払った金額まで返金できます。返金は、支払いが行われたモード（テストまたは本番）のシークレットキーで送信されるため、そのモードのキーが設定されている必要があります。入力した理由は、返金メモとして PayMongo に送信されます。PayMongo が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。成功した返金は、PayMongo の返金 ID とステータスを付けて、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。
モジュールはクレジットメモを作成しません。注文ページにある PrestaShop の標準の返金ボタンは、PayMongo を通じて返金しません。PayMongo ダッシュボードで行った返金は、PrestaShop に反映されません。代わりに注文ブロックから返金するか、注文を手動で更新してください。
ライセンスキー
モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox PayMongo Payment Gateway は、Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure ページの最上部にあるブロックで、設定の上にあります。License key にキーを入力して Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やドメインなど）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: presta-payment-paymongo の行と、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 アカウントで枠を解放してください。
有効なキーがない場合、PayMongo は購入者のチェックアウトに表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、支払い方法はあなたに対しても非表示になります。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も機能します。
ライセンスの期限が切れても、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は毎日、その後は毎週です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
PayMongo がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードにシークレットキーがあること（テストモードでは Test secret key、本番モードでは Live secret key）、カートが PHP 建てであること、そして合計金額が ₱100.00 以上であることを確認してください。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループについてモジュールが許可されているか確認してください。
支払いは完了したが、注文が作成されない：ウェブフックが機能しておらず、購入者がストアに戻っていません。PayMongo ダッシュボードで、使用しているモードにウェブフックがあること、その URL が Webhook URL に表示されたものと完全に一致すること、そして三つのイベントがすべて選択されていることを確認してください。その署名シークレットが対応するフィールド（Test webhook secret または Live webhook secret）に入力されているか確認してください。
ウェブフックが Invalid signature と応答する：そのモードの署名シークレットがないか、別のウェブフックのものです。ウェブフックの署名シークレットを、そのモードのフィールドに貼り付けてください。
ウェブフックが Mode mismatch と応答する：テストのイベントが本番として署名された、またはその逆です。各ウェブフックが正しいモードに属しているか確認してください。
ウェブフックが Temporary error と応答する：たとえば支払いのモードのシークレットキーがないために、PayMongo API を通じて支払いを確認できませんでした。PayMongo はウェブフックを自動的に再試行します。
ウェブフックが Busy, retry と応答する：同時に別のリクエストによって注文が確認中だったか、注文を作成できませんでした（たとえばモジュールが無効になっている場合）。PayMongo はウェブフックを自動的に再試行します。理由は Log に記録されています。
ウェブフックが Ignored と応答する：イベントは、このストアで開始されていない支払い、または別のモードの支払いに属しています。何も変更されません。
ブラウザでウェブフック URL に Method not allowed と表示される：これは正常です。この URL は PayMongo からのリクエストのみを受け付けます。
値が保存されない：キーが誤ったフィールドに貼り付けられています。シークレットキーは sk_test_ または sk_live_ で始まり、ウェブフックのシークレットは whsk_ で始まります。
購入者が PayMongo を選択するとエラーが表示される：モジュールのページにある Log フィールドを確認してください。誤ったシークレットキーの場合、支払い方法が一時的に利用できないというメッセージが表示されます。PayMongo アカウントで有効になっていない支払い方法があると、PayMongo がチェックアウトを拒否します。その場合は Payment methods からその方法を削除してください。
本番ストアでのテスト支払い：ストアが本番モードの間に届いたテスト支払いは、注文を PayMongo payment on hold にし、お金は受け取られていないというメモを付けます。本番の支払いは、テストモードに戻った後でも常に認識され、本番のキーで返金されます。
支払い後に注文が PayMongo payment on hold になっている：PayMongo payment ブロックのメモを読み（注文ステータスを参照）、その後で注文を処理するか、支払いを返金してください。
モードに関するメッセージで返金に失敗する：支払いはテストまたは本番モードで行われましたが、そのモードのシークレットキーが設定されていません。キーを入力してから、もう一度お試しください。
開発者は、actionPaymongoPCheckoutSessionData フックを使って Checkout Session のデータを変更できます。
アンインストール
Modules > Module Manager に移動し、VibeFox PayMongo Payment Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete data on uninstall がオンの場合、設定とログは削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の PayMongo ID、返金、および注文ステータス Awaiting PayMongo payment と PayMongo payment on hold は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、支払いメモと取引 ID を保持します。
PayMongo は、その所有者の商標です。本モジュールは PayMongo と提携しておらず、PayMongo の承認も受けていません。