VibeFox GoPay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

通貨: GoPay は CZK、EUR、PLN、USD、GBP、HUF、RON、BGN を受け付けます。カートの通貨がこれ以外の場合、決済ページでこの決済方法は表示されません。

GoPay アカウント: GoPay 加盟店アカウントの GoID、Client ID、Client Secret が必要です。これらはアカウントの連携設定にあります。サンドボックス（テスト）アカウントには独自の認証情報があります。通知のために GoPay アカウントで設定する項目はありませんが、ストアはインターネットから到達可能である必要があります。

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

インストール

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

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

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

4. サンドボックスの GoID、Client ID、Client Secret を入力し、Test Mode をオンのままにして、Enable/Disable をオンにし、Save をクリックします。

5. テスト注文をしてください。すべて正常に動作したら、本番環境の認証情報を入力し、Test Mode をオフにします。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox GoPay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上には、Sandbox mode — test payments only または Production mode — real payments が表示されます。現在のモードの GoID、Client ID、Client Secret が未入力の場合、また GoPay がストアの既定の通貨を受け付けない場合に警告が表示されます。いずれの場合も、決済ページには GoPay が表示されません。保存すると、キャッシュされた GoPay のアクセストークンが消去されるため、新しい認証情報がすぐに使用されます。

GoPay

Enable/Disable: Enable GoPay payment gateway で決済方法のオン／オフを切り替えます。初期値：オフ。

Title: 決済ページに表示される決済方法のタイトルです。注文に保存される決済方法名でもあります。初期値：GoPay。必須：空のタイトルは保存されません。

Description: 決済ページに表示される決済方法の説明です。初期値：Pay securely via GoPay - cards, wallets, bank transfers.

API 認証情報

GoID、Client ID、Client Secret は GoPay 加盟店アカウント（連携設定）に表示されます。サンドボックス（テスト）アカウントには独自の認証情報があります。API のドキュメントは doc.gopay.com にあります。

Test Mode: サンドボックスの認証情報を使い、決済を gw.sandbox.gopay.com に送信します。実際の料金は請求されません。本番環境の認証情報で実際の決済を受け付けるには、オフにします。初期値：オン。

Sandbox GoID: GoPay サンドボックス（テスト）アカウントの GoID です。

Sandbox Client ID: サンドボックスアカウントの OAuth Client ID です。

Sandbox Client Secret: サンドボックスアカウントの OAuth Client Secret です。

Production GoID: GoPay 加盟店 ID（GoID）です。

Production Client ID: GoPay から提供される OAuth Client ID です。

Production Client Secret: GoPay から提供される OAuth Client Secret です。

GoID は数字のみで構成されます（例：8123456789）。それ以外の値を入力すると、ページにエラーが表示され、以前の値が保持されます。

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

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

決済

Payment Page Language: GoPay の決済ページの言語です。初期値：Automatic (site language, then billing country)。自動の場合は、お客様のカートの言語が使われます。GoPay がその言語に対応していない場合は請求先の国で決まり、それ以外では英語が使われます。また、次の 19 言語から固定することもできます：Czech、English、Slovak、German、Polish、Hungarian、Romanian、Bulgarian、Croatian、Slovenian、Estonian、Latvian、Lithuanian、French、Italian、Spanish、Portuguese、Ukrainian、Russian。

Order Status After Payment: 決済が確認されたときに設定される注文ステータスです。

注文と一致しない決済、キャンセル後の決済、事前承認された決済は、必ず GoPay payment on hold になります。

決済通知

通知は、決済が行われたことをストアに知らせます。Notification URL はこのセクションに表示され、決済のたびに GoPay に送信されるため、GoPay アカウントでの設定は不要です。フレンドリー URL の場合、次のような形式になります：https://your-shop/module/wcp_gopay_gateway/webhook。/en/ のような言語コードが付くこともあります。この URL はインターネットから到達可能である必要があります。前段にパスワード保護やファイアウォールを置かないでください。ストアがメンテナンスモードの間も機能し、ストアの国による制限にもブロックされません。

GoPay の通知には決済 ID のみが含まれ、署名はありません。通知はそれぞれ、決済が行われたモードの認証情報を使って GoPay API に決済の状態を問い合わせることで検証されます。また、決済はモジュールがストアのカートに対して作成したものである必要があります。GoPay から状態を読み取れない場合、ストアはエラーを返し、GoPay は通知を再送します。通知がない場合、お客様が決済後にストアへ戻ったときにのみ注文が作成されます。

詳細設定

Logging: GoPay のイベントを、モジュールフォルダ内の logs/gopay_p_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。エラーと警告は常に記録されます。認証情報、トークン、カードデータ、お客様のメールアドレスと氏名は記録されません。初期値：オフ。

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

Delete Data on Uninstall: オンの場合、モジュールをアンインストールすると、モジュールの設定、キャッシュされた GoPay のアクセストークン、ログが削除されます。注文、その GoPay 決済データ、注文ステータス GoPay payment on hold は常に残ります。初期値：オフ。

チェックアウト

決済ステップで、お客様は決済方法（初期値は GoPay）を選んで確定します。モジュールは、カート合計をカートの通貨で、商品、配送料、ギフトラッピングを含めて GoPay の決済を作成し、お客様を GoPay の決済ページへ移動させます。そこで GoPay は、GoPay アカウントで有効になっている決済方法（決済カード、銀行振込、デジタルウォレットなど）を提示します。お客様の請求先氏名、メールアドレス、電話番号、住所は GoPay に渡されます。空欄の項目は送信されません。GoPay 上では、決済は Order PS- とカート番号で表示されます。この時点ではまだ注文は存在しません。

決済後、お客様はストアに戻ります。注文は、GoPay が決済を確認した後にのみ支払い済みとしてマークされます。確認は、通知によるもの、またはお客様が戻ったときに GoPay API へ行うリクエストによるものです。同時に届いた通知と戻りは、順番に処理されるため、注文は 1 つだけ作成されます。その後、お客様には標準の注文確認ページが表示されます。注文が GoPay payment on hold になった場合、ページには Your payment is being reviewed. We will contact you if anything else is needed. というメッセージが追加されます。

お客様が戻った時点で GoPay がまだ決済を確認していない場合（例：銀行振込が処理中、または GoPay に接続できない場合）、Payment confirmation ページに GoPay 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 ボタンが表示されます。

決済が完了しなかった、キャンセルされた、または期限切れになった場合、お客様はチェックアウトに戻り、The GoPay payment was not completed. You can try again or choose another payment method. または The GoPay payment was cancelled or has expired. You can try again or choose another payment method. と表示されます。カートは保持され、再度試すと新しい GoPay の決済が作成されます。すでに注文があるカートに再度請求されることはありません。

GoPay が決済を開始できない場合、お客様はチェックアウトに留まり、短いメッセージが表示されます。例：GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. または GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. 技術的な原因はログに記録されます。

お客様は GoPay のページで決済方法を選択します。PrestaShop 上では選択できません。モジュールは、サブスクリプションや継続課金、保存済みカード、埋め込み型決済フォーム、PrestaShop からの事前承認のキャプチャや取り消しには対応していません。

注文と返金

注文ステータス

No order yet: お客様は GoPay に移動しましたが、まだ支払っていないか、GoPay がまだ決済を確認していません。カートだけが存在します。

Payment accepted or Delivered: 決済が確認されました。ステータスは Order Status After Payment に従います。決済は GoPay の決済 ID をトランザクション ID として記録され、備考に決済 ID と決済手段が表示されます。

GoPay payment on hold: GoPay は決済を確認しましたが、金額、通貨、または注文番号がカートと一致しません（例：決済の開始後にカートが変更された）。または、注文がキャンセルされた後に決済が届いた。または、決済は事前承認のみで、まだ入金されていません。備考に理由が記載されます。事前承認された決済は GoPay でキャプチャする必要があります。GoPay が決済を完了と報告すると、注文は支払い済みのステータスに移ります。

Refunded: 注文の GoPay 決済が、モジュール経由または GoPay アカウントで全額返金されました。

すでに支払い済みの注文に対して別の決済試行も支払われた場合、注文は変更されません。備考で、GoPay アカウントで重複分を返金するよう求められます。GoPay なしで（例：手動で）すでに支払い済みとマークされた注文に対して GoPay の決済が行われた場合にも、同様の備考が追加されます。キャンセル済みまたは返金済みの注文は、その後の通知によって再オープンされることはありません。

GoPay 決済ブロック

注文ページには GoPay payment ブロックが表示され、GoPay 決済 ID、GoPay の状態と決済手段、決済金額、支払い済み金額と返金済み金額、サンドボックス決済の Sandbox バッジ、手動確認の理由、返金履歴、注文の GoPay notes が含まれます。

返金

GoPay payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via GoPay をクリックします。Refund this amount through GoPay? This cannot be undone. の確認に同意します。全額返金と一部返金に対応しています。注文を編集する権限が必要です。Modules ページへのアクセスは必要ありません。GoPay が一部返金を受け付けるのは、決済から 24 時間以内のみです。返金は GoPay が請求した金額と通貨で行われるため、金額または通貨が一致しなかった場合は、お客様が実際に支払った金額まで返金できます。返金は決済が行われたモード（サンドボックスまたは本番環境）で送信されるため、そのモードの認証情報が設定されている必要があります。GoPay が返金を拒否した場合、ブロックには GoPay のメッセージが表示され、返金は記録されません。成功した返金は返金履歴と備考に追加されます。GoPay が後日処理するために受け付けた返金は、受付済みとして記録されます。全額返金すると、注文は Refunded になります。一部返金ではステータスは変わりません。

モジュールは貸方伝票（credit slip）を作成しません。注文ページの PrestaShop 標準の返金ボタンでは、GoPay を通じて返金されることはありません。

GoPay アカウントで行われた返金は、通知によって反映されます。全額返金の場合、注文は Refunded に変わります。一部返金の場合は備考が追加されます。これらはブロックの返金履歴には追加されません。

ライセンスキー

このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox GoPay Gateway のライセンスブロックは、Modules > Module Manager > VibeFox GoPay Gateway > Configure ページで設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態、ステータス（ライセンスの有効期限日や、お使いのドメインなど）、そして、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-gopay の行と、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 と日付）。ストアの URL を変更した後や、アカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。メインストアのドメインを指し、マルチストア構成でも同様です。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、決済ページで GoPay はお客様に表示されません。決済が開始された場合、お客様には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、決済方法はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、決済ページでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、返金も行えます。

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

トラブルシューティング

GoPay がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに GoID、Client ID、Client Secret が設定されていること、カートの通貨が CZK、EUR、PLN、USD、GBP、HUF、RON、BGN のいずれかであることを確認してください。認証情報が未入力の場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、お客様の国、お客様のグループに対してモジュールが許可されているか確認してください。

決済は完了したが、注文が作成されなかった：GoPay が設定に表示されている Notification URL に接続できず、お客様もストアに戻りませんでした。URL をブロックしているパスワード保護やファイアウォールのルールを削除してください。決済が行われたモードの認証情報が設定されているか確認してください。各通知はその認証情報で検証されるためです。Logging をオンにして、Log フィールドを確認してください。GoPay は、成功の応答を受け取れなかった通知を再送します。

Notification answers Order not found: この決済はこのストアで作成されたものではないか、そのカートが削除されています。

Notification answers Payment state could not be verified: GoPay API に接続できなかったか、そのモードの認証情報が未入力または誤りです。GoPay は通知を再送します。

Notification answers Busy, retry later: 同じ時点で別のリクエストがカートを処理していたか、注文を作成できませんでした（例：モジュールが無効）。GoPay は通知を再送します。理由を確認するには Logging をオンにしてください。

お客様が GoPay を選んだときにエラーが表示される：Logging をオンにして、Log フィールドを確認してください。認証情報が誤っている、またはもう一方のモードの認証情報である場合が一般的な原因です。請求情報に関するメッセージは、GoPay がメールアドレス、電話番号、住所を受け付けなかったことを意味します。

テスト決済では本番の注文が確認されない：サンドボックスと本番環境は分けて扱われます。各決済は、作成されたモードで確認されます。Test Mode を使いたいモードに切り替え、そのモードの認証情報を使用してください。

決済後に注文が GoPay payment on hold になる：GoPay payment ブロックの備考を確認してください。支払われた金額または通貨がカートと一致しなかった、注文のキャンセル後に決済が届いた、または決済が事前承認のみである、のいずれかです。

返金に失敗する：ブロック内の GoPay のメッセージを確認してください。一部返金は決済から 24 時間以内のみ可能です。モードに関するメッセージは、決済がサンドボックスまたは本番環境モードで行われ、そのモードの認証情報が設定されていないことを意味します。

開発者向け：actionGopayPaymentPayload フックは、決済リクエストが GoPay に送信される前に、その内容を変更します。

アンインストール

Modules > Module Manager に移動し、VibeFox GoPay Gateway の横にあるメニューを開いて、Uninstall を選択します。ライセンスキーとこのモジュールのライセンス状態は、常に削除されます。Delete Data on Uninstall がオンの場合、モジュールの設定、キャッシュされた GoPay のアクセストークン、ログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の GoPay 決済データと注文ステータス GoPay payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、決済の備考とトランザクション ID を保持します。

GoPay は各所有者の商標です。本モジュールは GoPay と提携しておらず、GoPay による承認も受けていません。