VibeFox Przelewy24 for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

WooCommerce: 7.0 以降。インストールされて有効になっている必要があります。WooCommerce がないと、プラグインを有効化できません。

PHP: 8.0 以降。

通貨: 注文は PLN、EUR、GBP、CZK のいずれかである必要があります。その他の通貨の場合、チェックアウトではこの決済方法は表示されません。注文は元の通貨で請求されます。プラグインは通貨を換算しません。

Przelewy24 アカウント: Przelewy24 の加盟店アカウントと、その API データが必要です。Merchant ID、API キー（Przelewy24 の管理画面では report key と呼ばれます）、CRC キー、そしてストアに固有の ID がある場合は POS ID（Shop ID）です。これらは、panel.przelewy24.pl にある Przelewy24 加盟店管理画面の My data > API data and configuration で確認できます。サンドボックスのキーは、sandbox.przelewy24.pl/panel にある別のサンドボックスアカウントから取得します。Przelewy24 の管理画面でほかに設定することはありません。プラグインは、すべての支払いとともに通知 URL を送信します。Przelewy24 は支払い通知をこの URL に送信するため、サイトはインターネットから到達可能である必要があります。

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

インストール

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

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

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

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

5. サンドボックスのキー（Merchant ID、API key、CRC key。POS ID は Merchant ID と異なる場合のみ）を入力し、Enable/Disable を有効にして保存し、サンドボックスモードでテスト支払いを行います。

6. 本番キー（Live）を入力し、Test Mode のチェックを外して保存すると、実際の支払いを受け付けます。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Przelewy24。項目の上には、不足している内容がある場合の警告が表示されます。サンドボックスが有効な間は次のように表示されます：Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. 現在のモードのキーが不完全な場合は次のように表示されます：Enter the Sandbox Merchant ID, API key and CRC key — until then Przelewy24 is not shown at checkout.（本番キーの場合も同様）。Przelewy24 がストアの通貨を受け付けない場合、警告にはその通貨と対応している通貨が示されます。保存すると、警告はすぐに新しいモードとキーを反映します。Przelewy24 の管理画面からキーと一緒にコピーされたスペースや改行は、保存時に削除されます。

チェックアウト

Enable/Disable: Enable Przelewy24 Payment は、この決済方法を有効または無効にします。既定値: 無効。

Title: チェックアウトで購入者に表示される決済方法の名前。既定値: Przelewy24。

Description: チェックアウトで決済方法の下に表示されるテキスト。既定値: Pay with BLIK, online bank transfer or card via Przelewy24.

API 認証情報

このセクションでは、キーの場所（Przelewy24 加盟店管理画面の My data > API data and configuration）を説明し、panel.przelewy24.pl と sandbox.przelewy24.pl/panel へのリンクを示します。

Test Mode: Enable sandbox (test) mode。有効にすると、新しい支払いはサンドボックスのキーを使って Przelewy24 サンドボックス（sandbox.przelewy24.pl）に送られ、実際の支払いは発生しません。チェックを外すと、本番キーを使って secure.przelewy24.pl で実際の支払いを受け付けます。既定値: 有効。

本番キー

Live Merchant ID: Przelewy24 の加盟店 ID。数字のみ。

Live POS ID (optional): Shop ID（posId）。Merchant ID と同じ場合は空欄のままにします。

Live API key (report key): Przelewy24 の管理画面にある API キー。POS ID と組み合わせて API 認証に使用されます。

Live CRC key: Przelewy24 へのリクエストに署名し、Przelewy24 からの通知の署名を検証するために使用されます。

サンドボックスキー

Sandbox Merchant ID: Przelewy24 のサンドボックスアカウントの Merchant ID。

Sandbox POS ID (optional): サンドボックスアカウントの Shop ID（posId）。Merchant ID と同じ場合は空欄のままにします。

Sandbox API key (report key): サンドボックスアカウントの API キー。

Sandbox CRC key: サンドボックスアカウントの CRC キー。リクエストへの署名とサンドボックス通知の検証に使用されます。

本番キーとサンドボックスキーは別物です。Merchant ID と POS ID には数字のみを使用する必要があります。現在のモードの Merchant ID、API key、CRC key を入力するまで、決済方法はチェックアウトに表示されません。あるモードで開始された支払いは、モードを切り替えた後も、常にそのモードのキーで検証・返金されます。そのため、古いモードの支払いがまだ未完了であるか、返金の可能性がある間は、そのモードのキーを保管しておいてください。

支払い通知

このセクションには、ストアの通知 URL が表示されます。形式は次のとおりです：https://your-site/wc-api/wc_p24_payment/。プラグインはすべての支払いとともにこの URL を Przelewy24 に送信するため、Przelewy24 の管理画面で設定する必要はありません。返金結果も同じ URL で受け取ります。この URL はインターネットから到達可能である必要があります。前段にファイアウォール、メンテナンスモード、HTTP 認証があってはなりません。通知がなくても、購入者が注文受付ページに戻った時点で支払いは確定します（チェックアウトを参照）。購入者が戻らない場合、注文は「支払い待ち」のままになります。

詳細設定

Debug Log: Enable logging は、技術的なイベント（注文番号、P24 トランザクション ID、エラー）を WooCommerce > Status > Logs に、ソース wcp_przelewy24_payment として書き込みます。エラーと警告は常に記録されます。キー、リクエスト本文、個人データは記録されません。既定値: 無効。

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted。注文とその支払いデータは削除されません。プラグインを無効化すると、すべてが保持されます。既定値: 無効。

チェックアウト

購入者は決済方法（既定では Przelewy24。チェックアウトブロックには P24 のロゴが表示されます）を選択し、注文します。サンドボックスモードでは、チェックアウトブロックに Sandbox mode — no real money is charged と表示されます。プラグインは、注文の通貨で注文合計額に対する Przelewy24 トランザクションを登録し、購入者のメールアドレス、氏名、請求先の国を含め、セッション ID とモード（サンドボックスまたは本番）を含む注文メモを追加します。支払いの試行ごとに、それぞれ独自のセッション ID が割り当てられます。購入者は Przelewy24 の決済ページに移動し、BLIK、オンラインバンク振込、カード、または Przelewy24 アカウントで有効になっているその他の方法で支払いを行います。決済ページは、Przelewy24 が対応している場合はサイトの言語で表示され、それ以外は英語で表示されます。

Przelewy24 が確認するまで、注文は支払い済みになりません。Przelewy24 は署名付きの通知をストアに送信します。プラグインは、CRC キー、Merchant ID、POS ID で署名を検証し、そのセッションがこの注文について同じモードで登録されていたかを確認し、金額と通貨が支払い試行および現在の注文合計と一致するかを確認します。その後にのみ、Przelewy24 で取引を検証し（Przelewy24 は検証済みの支払いのみを入金します）、注文を支払い済みにします。有効な署名のないウェブフックは拒否されます。

支払い後、購入者は注文受付ページに戻ります。通知がまだ届いていない場合、プラグインは認証済みのサーバー間リクエストで Przelewy24 に取引のステータスを問い合わせ（注文ごとに 10 秒に 1 回まで）、同じチェックを適用します。戻りページだけで注文が支払い済みになることはありません。支払いが確定するまで、ページには We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: と表示され、Pay for order ページを開く Pay again ボタンが表示されます。注文が保留中の場合、ページには Your payment is being verified. We will send you an e-mail as soon as it is confirmed. と表示されます。同じ注文の古い Przelewy24 ページから後で行われた支払いも、引き続き受け付けられます。

支払いを開始できない場合、購入者には短いメッセージが表示されます。Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method.（理由はログに記録されます）、Payment gateway is not configured properly. Please contact the administrator.（現在のモードのキーが未設定）、注文の通貨では Przelewy24 が支払いを受け付けられないというメッセージ、または The order total must be greater than zero. のいずれかです。すでに支払い済みまたは保留中の注文は、Przelewy24 に再送信されません（This order does not need a payment any more.）。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文保存（HPOS）に対応しています。

本プラグインは、保存済みカードやワンクリック決済、サブスクリプションや定期決済、チェックアウトページでの P24 決済方法（BLIK コード入力欄など）の選択、分割払いウィジェットには対応しておらず、カートの内容を Przelewy24 に送信しません。

注文と返金

注文ステータス

Pending payment: 購入者は Przelewy24 に移動しましたが、まだ支払っていないか、支払いがまだ確定していません。

Processing or Completed: 支払いが検証されました。WooCommerce は、「処理中」を設定します。ダウンロード可能な仮想商品のみの注文の場合は「完了」を設定します。注文メモには、P24 注文 ID、金額、モードが表示されます。注文のトランザクション ID は P24 注文 ID です。各支払いは 1 回だけ適用されます。

On hold: Przelewy24 が報告した金額または通貨が注文と異なります（たとえば、支払い開始後に注文合計が変更された場合）。支払いは確定しておらず、その旨がメモに記載されます。または、キャンセルされた注文に対して支払いが届き、検証されました。注文は黙って再開されず、メモには注文の発送または支払いの返金を依頼する内容が表示されます。Przelewy24 の管理画面で支払いを確認してください。

すでに支払い済みまたは返金済みの注文に対して 2 回目の支払いが届いた場合（古い支払いリンク、ブラウザのタブが 2 つあるなど）、その支払いは確定されず、Przelewy24 から入金されません。注文のメモには、Przelewy24 の管理画面で確認し、必要に応じて購入者に返金するよう示されます。

返金

注文を開き、Refund をクリックし、金額を入力して Refund via Przelewy24 をクリックします。全額返金と一部返金に対応しています。返金は、支払いが行われたモード（サンドボックスまたは本番）で送信されるため、そのモードのキーが設定されている必要があります。Przelewy24 は返金を非同期で処理します。最初に注文メモに返金がリクエストされたことが表示され、結果は後で通知 URL に届き、メモとして追加されます。Przelewy24: refund of … completed. という内容、または返金が拒否されて金額が返金されなかったことを示すメモです。返金が拒否された場合は、Przelewy24 の管理画面で確認してください。注文にすでに記録されている WooCommerce の返金は、自動的には削除されません。

Przelewy24 が返金リクエストを受け付けない場合、WooCommerce は理由とともに Przelewy24 refund failed: を表示し、返金は記録されません。Przelewy24 の管理画面で直接行った返金は、注文には追加されません。

ライセンスキー

本プラグインは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロックは、WooCommerce > Settings > Payments > Przelewy24 の上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ステータス（例：ライセンスの有効期限日）とドメインが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。

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

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

ライセンスの期限が切れても、プラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、バックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Przelewy24 が表示されない: ライセンスが有効であること、Enable/Disable が有効であること、現在のモードの Merchant ID、API key、CRC key が入力されていること（Test Mode が有効な間はサンドボックスキー、それ以外は本番キー。Merchant ID と POS ID は数字のみ）、注文の通貨が PLN、EUR、GBP、CZK のいずれかであることを確認してください。設定の上部の警告に問題が示されています。開発者は、フィルター wc_p24_supported_currencies で通貨リストを変更できます（Przelewy24 アカウントで有効になっている、小数点以下 2 桁の通貨のみ）。

支払いは完了したが、注文が Pending payment のまま: Przelewy24 からの通知がストアに届かず、購入者も注文受付ページに戻りませんでした。Payment notifications に表示されている URL がインターネットから到達可能であること（/wc-api/wc_p24_payment/ の前にメンテナンスモード、ファイアウォール、HTTP 認証がないこと）、そして支払いのモードの Merchant ID、POS ID、CRC key が正しいことを確認してください。拒否された通知は、Debug Log がオフでも WooCommerce > Status > Logs にソース wcp_przelewy24_payment として記録されます。

ストアが通知にどう応答するか: 処理済み、重複、または不明な通知には HTTP 200 で応答します。それ以外の場合、Przelewy24 は後で再送します。400（データが不足または不正）、401 Invalid signature（CRC キーが誤っている、Merchant ID または POS ID が異なる、または支払いとは別のモードのキーで署名された通知）、405（POST リクエストではない）、500 Verification failed（Przelewy24 での検証が失敗した。注文にメモが 1 回追加される）、503 Busy, retry later（同時に別のリクエストが注文を更新していた）。

購入者に Payment error: Przelewy24 could not start the payment: と表示される: Przelewy24 がトランザクションを拒否しました。通常は、現在のモードのキーが誤っていることが原因です（サンドボックスキーはサンドボックスモードでのみ、本番キーは本番モードでのみ機能します）。Przelewy24 からのエラーはログに記録されています。

支払い後に注文が On hold になる: 注文メモを確認してください。金額または通貨が注文と異なっていたか、キャンセルされた注文に対して支払いが届きました。Przelewy24 の管理画面で支払いを確認し、その後、注文を処理するか支払いを返金してください。

返金が失敗する: This order has no verified Przelewy24 payment. Cannot process refund. は、注文が検証済みの Przelewy24 の支払いで支払われていないことを意味します。The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing.（本番の場合も同様）は、支払いのモードのキーが削除されたことを意味します。キーを再入力してください。

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除します。このプラグインのライセンスキーとライセンスステータス、および戻りページの一時的なマーカーは、常に削除されます。プラグインの設定とそのログ（ローテーションされたログファイルを含むログファイル、およびソース wcp_przelewy24_payment のデータベースログエントリー）は、Delete data on uninstall が有効な場合にのみ削除されます。それ以外の場合は、後で再インストールできるように保持されます。既存の注文は、支払いメモ、トランザクション ID、Przelewy24 の支払いデータを保持します。

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