VibeFox GoPay for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.6 以降。インストールされ、有効化されている必要があります。WooCommerce がない場合、プラグインは有効化できません。

PHP: 8.0 以降。

通貨: GoPay は CZK、EUR、PLN、USD、GBP、HUF、RON、BGN に対応しています。それ以外の通貨では、チェックアウトに決済方法が表示されません。

GoPay アカウント: GoPay 加盟店アカウントの GoID、Client ID、Client Secret が必要です。これらはアカウントの連携設定にあります。サンドボックス（テスト）アカウントには専用の認証情報があります。通知のために GoPay アカウントで設定することはありませんが、ストアにインターネット経由でアクセスできる必要があります。

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin に移動し、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_gopay_gateway フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます：WooCommerce > Settings > Payments > GoPay > Manage に移動するか、Plugins ページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。

5. サンドボックスの GoID、Client ID、Client Secret を入力し、Test Mode をオンにしたまま Enable/Disable を有効にします。

6. テスト注文を行います。すべて正常に動作したら、本番環境の認証情報を入力し、Test Mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > GoPay。決済ゲートウェイの説明の下に Sandbox mode — test payments only または Production mode — real payments が表示されます。現在のモードの GoID、Client ID、Client Secret が未入力の場合や、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: Enable sandbox/test mode を有効にすると、サンドボックスの認証情報を使って決済が gw.sandbox.gopay.com に送られます。実際の請求は行われません。無効にすると、本番環境の認証情報（gate.gopay.cz）で実際の決済を受け付けます。既定値：オン。

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。別の値を入力するとエラーが表示され、前の値が保持されます。

決済

Payment Page Language: GoPay 決済ページの言語です。既定値：Automatic (site language, then billing country)。自動ではサイトの言語が使用されます。GoPay がその言語に対応していない場合は請求先の国に基づき、それ以外の場合は英語が使用されます。次の 19 言語から 1 つを指定することもできます：チェコ語、英語、スロバキア語、ドイツ語、ポーランド語、ハンガリー語、ルーマニア語、ブルガリア語、クロアチア語、スロベニア語、エストニア語、ラトビア語、リトアニア語、フランス語、イタリア語、スペイン語、ポルトガル語、ウクライナ語、ロシア語。

Order Status After Payment: 決済の確定後に注文へ設定するステータスです。ステータスはすぐに設定され、ステータス変更は 1 回だけ行われ、購入者へのメールも 1 通だけ送られます。

決済通知

通知は決済が行われたことをストアに知らせます。通知 URL は決済ごとに GoPay へ送信されるため、GoPay アカウントで設定する必要はありません。設定に URL が表示されます。形式は https://your-site/?gopay-api=gopay_payment_notification のようになります。インターネットからアクセスできる必要があります。パスワード保護、メンテナンスモード、前段のファイアウォールでブロックしないでください。

GoPay 通知に含まれるのは決済 ID だけで、署名はありません。すべての通知について GoPay API に決済状況を問い合わせて検証し、さらにその決済がストアの注文に対してプラグインで作成されたことを確認します。GoPay から状況を取得できない場合、ストアはエラーを返し、GoPay は通知を再送します。通知がない場合、購入者が支払い後にストアへ戻ったときにのみ注文が確定します。

詳細設定

Logging: Enable logging を有効にすると、GoPay のイベントが WooCommerce > Status > Logs にソース wcp_gopay_gateway として記録されます。エラーは常に記録されます。認証情報、トークン、カードデータ、購入者のメールアドレス、電話番号、住所は記録されません。既定値：オフ。

Delete Data on Uninstall: Delete plugin settings, cached access tokens and log files when uninstalled を有効にすると、プラグインの削除時にゲートウェイ設定、キャッシュされた GoPay アクセストークン、ログが削除されます。既定値：オフ。

チェックアウト

購入者は決済方法（既定では GoPay）を選び、注文します。プラグインは注文の商品、送料、手数料を含む合計金額を注文通貨で GoPay 決済として作成し、購入者を GoPay 決済ページに送ります。GoPay では、アカウントで有効になっている決済カード、Apple Pay、Google Pay、銀行振込などの決済方法が表示されます。購入者の請求先氏名、メールアドレス、電話番号、住所が GoPay に渡されます。空欄は送信されません。GoPay では決済が Order と注文番号で表示されます。

支払い後、購入者はストアに戻ります。GoPay が通知または購入者の戻り時に行う GoPay API へのリクエストで決済を確認した後にのみ、注文が支払い済みになります。通知と戻りが同時に届いた場合は順番に処理されるため、注文が二度完了することはありません。決済が確定すると、購入者は注文受付ページに移動します。

決済が完了しなかった場合、キャンセルされた場合、または有効期限が切れた場合、購入者は Pay for order ページに移動し、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. というメッセージが表示されます。このページから未払いの注文を再度支払うことができます。すでに支払い済みの注文に対して、2 回目の 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. 技術的な理由は注文メモに追加されます。

この決済方法はクラシックチェックアウト、Cart と Checkout ブロック、Pay for order ページで動作します。サンドボックスモードでは Checkout ブロックに Sandbox mode: no real payment will be made. と表示されます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

購入者が決済方法を選ぶのは GoPay のページであり、WooCommerce 内では選べません。本プラグインはサブスクリプションや継続課金、保存済みカード、埋め込み型決済フォーム、WooCommerce からの事前承認のキャプチャや取り消しには対応していません。

注文と返金

注文ステータス

Pending payment: 購入者が GoPay に移動したものの、まだ支払っていないか、GoPay がまだ決済を確認していません。

Processing or Completed: 決済が確定しました。ステータスは Order Status After Payment に従います。注文メモには GoPay 決済 ID と決済手段が表示されます。取引 ID は GoPay 決済 ID です。

On hold: GoPay は決済を確認しましたが、金額または通貨が注文と異なります。注文がキャンセルされた後に決済が届いた場合、または事前承認のみでまだ資金がキャプチャされていない場合も該当します。理由は注文メモに記載されます。事前承認済みの決済は GoPay でキャプチャしてから、注文を手動で完了してください。

Failed: 未払い注文に対する最後の GoPay 決済がキャンセルされたか、有効期限が切れました。

Refunded: 注文の GoPay 決済が全額返金されました（GoPay アカウントでの返金など）。

すでに支払い済みの注文に対する別の決済も成功した場合、注文は変更されません。重複分を GoPay アカウントで返金するよう注文メモに記載されます。GoPay を使わず（たとえば手動で）支払い済みとした注文について GoPay 決済が行われた場合も、同様のメモが追加されます。支払い済みの注文をキャンセルまたは返金した後は、後から通知が届いても注文が再開されることはありません。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via GoPay をクリックします。全額返金と一部返金に対応しています。GoPay が一部返金を受け付けるのは決済から 24 時間後のみです。返金は決済時に使用したモード（サンドボックスまたは本番環境）で送信されるため、そのモードの認証情報を設定する必要があります。GoPay が返金を拒否した場合、WooCommerce に GoPay のメッセージが表示され、返金は記録されません。成功した返金は注文メモに追加されます。後で処理するため GoPay が受け付けた返金も、受付済みとして記録されます。

GoPay アカウントで行われた返金は通知で届きます。全額返金では注文が「返金済み」に変更され、一部返金では注文メモが追加されます。WooCommerce の返金として自動記録されることはありません。

ライセンスキー

本プラグインは vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > GoPay の上部にあります。キーを License key に貼り付け、Activate をクリックします。欄にはライセンスの有効期限やドメインなどの状態が表示されます。Check now で状態を再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから vibefox.net アカウントを開けます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメイン枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、チェックアウトに GoPay は表示されません。それでも決済を開始すると、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、キーを購入する前に設定やテストができるよう、(unlicensed — visible to admins only) と付いた決済方法が引き続き表示されます。Plugins ページと WooCommerce のページにリマインダーが表示されます。既存の注文への影響はありません。開始済みの決済は引き続き確定され、返金も機能します。

ライセンスの有効期限が切れてもプラグインは動作しますが、更新とサポートを受けるにはライセンスの更新が必要です。状態はバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに GoPay が表示されない：ライセンスが有効であること、Enable/Disable が有効であること、現在のモードに GoID、Client ID、Client Secret が設定されていること、通貨が CZK、EUR、PLN、USD、GBP、HUF、RON、BGN のいずれかであることを確認してください。Pay for order ページでは注文の通貨が使われます。認証情報または通貨に誤りがある場合、設定ページに警告が表示されます。

決済は完了したが、注文が Pending payment のまま：GoPay が設定ページの通知 URL に接続できず、購入者もストアに戻っていません。URL をブロックするパスワード保護、メンテナンスモード、ファイアウォールルールを解除してください。通知は決済時のモードの認証情報で検証されるため、その認証情報が設定されていることを確認してください。WooCommerce > Status > Logs のソース wcp_gopay_gateway を確認します。正常な応答を受け取れなかった通知は GoPay が再送します。

通知に「Order not found」と表示される：このストアが決済を作成していないか、該当する注文が削除されています。

通知に「Payment state could not be verified」と表示される：GoPay API に接続できないか、そのモードの認証情報に誤りがあります。GoPay は通知を再送します。

注文時に購入者にエラーが表示される：注文メモを開くか、Logging を有効にしてください。メモに GoPay のエラーが表示されます。通常は認証情報が間違っているか、別モードの認証情報が使われています。請求先情報に関するメッセージは、GoPay がメールアドレス、電話番号、住所を受け付けなかったことを示します。

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

決済後に注文が On hold：注文メモを確認してください。決済額または通貨が注文と異なる、注文のキャンセル後に決済が届いた、または決済が事前承認のみのいずれかです。

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

ライセンス欄にエラーが表示される：欄のメッセージに従ってください。キーが別のドメインですでに使用されている場合は、vibefox.net アカウントで枠を解放してから Check now をクリックします。サイトアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効にします。ライセンスサーバーに接続できなくても、プラグインは最後に確認された状態で動作を続けます。

開発者向け：フィルター gopay_p_payment_payload は決済リクエストを変更し、gopay_p_icon は決済方法のアイコンを変更します。

アンインストール

プラグインを無効化してもデータは保持されます。削除するには、Plugins ページで無効化して削除します。このプラグインのライセンスキーとライセンス状態は常に削除されます。ゲートウェイ設定、キャッシュされたアクセストークン、ログは、Delete Data on Uninstall が有効な場合にのみ削除されます。それ以外の場合は、後で再インストールできるよう保持されます。注文に保存された GoPay 決済 ID は常に保持されます。既存の注文の決済メモと取引 ID も保持されます。

GoPay はそれぞれの所有者の商標です。本プラグインは GoPay と提携しておらず、GoPay の承認も受けていません。