VibeFox Przelewy24 for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。

通貨: カートは PLN、EUR、GBP、CZK のいずれかである必要があります。それ以外の通貨では、注文手続きで支払い方法が表示されません。カートはその通貨で請求されます。モジュールは通貨換算を行いません。

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

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

インストール

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

2. アップロードが完了したら Configure をクリックするか、後で VibeFox Przelewy24 Payment をモジュールの一覧から探して Configure をクリックします。

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

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

5. 本番のキーを入力し、Test Mode をオフにして Save をクリックすると、実際の支払いを受け付けます。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Przelewy24 Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上には、不足している内容がある場合に警告が表示されます。サンドボックスがオンの間は、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 の管理画面からキーと一緒にコピーされたスペースや改行は、保存時に削除されます。

Przelewy24

Enable/Disable: Enable Przelewy24 Payment は支払い方法を有効または無効にします。既定：無効。

Title: 購入者が注文手続きで見る支払い方法の名前です。注文に保存される支払い方法名でもあります。既定：Przelewy24。必須：タイトルを空にして保存すると、Enter a title for the payment method. と表示されます。

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: Przelewy24 のサンドボックス（sandbox.przelewy24.pl）とサンドボックスのキーを使用します。実際の料金は請求されません。オフにすると、本番キーを使って secure.przelewy24.pl で実際の支払いを受け付けます。既定：オン。オンの間、購入者には支払い方法の下に Sandbox mode - no real money is charged と表示されます。

本番キー

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

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

Live API key (report key): Przelewy24 の管理画面にある API キーです。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 キーです。リクエストへの署名とサンドボックス通知の検証に使用されます。

保存済みの API キーと CRC キーは二度と表示されません。フィールドは空のままで、Saved - leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

Clear saved secrets: キーにチェックを入れて Save をクリックすると、そのキーが削除されます。空のフィールドでは保存済みの値が維持されます。

本番キーとサンドボックスのキーは異なります。Merchant ID と POS ID は数字のみでなければなりません。現在のモードの Merchant ID、API キー、CRC キーが入力されるまで、注文手続きに支払い方法は表示されません。あるモードで開始された支払いは、モードを切り替えた後も、常にそのモードのキーで検証され、返金されます。そのため、古いモードの支払いが未完了であるか返金の可能性がある間は、そのモードのキーを保管しておいてください。

支払い通知

Notification URL: Przelewy24 からの支払い通知を受け取るアドレスです。フレンドリー URL を使用している場合は https://your-shop/module/wcp_przelewy24_payment/notify のような形になり、/en/ のような言語コードが含まれることもあります。モジュールはすべての支払いと返金のたびにこの URL を Przelewy24 に送信するため、Przelewy24 の管理画面で設定する必要はありません。この URL はインターネットから到達可能である必要があります。前段にファイアウォールや HTTP 認証があってはなりません。ストアがメンテナンスモードの間も動作を続け、ストアの国別制限によってブロックされることもありません。通知がなくても、購入者がストアに戻ったときに支払いは確定します（注文手続きを参照）。購入者が戻らない場合は、注文は作成されません。

詳細設定

Debug Log: 技術的なイベント（カート番号、P24 取引 ID、エラー）を、モジュールフォルダ内の logs/wc_p24_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。拒否された通知や、検証・返金の失敗などのエラーと警告は常に記録されます。スイッチをオンにすると、すべての手順も記録されます。キー、リクエスト本文、個人データは一切記録されません。既定：オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定とログが削除されます。注文と、その Przelewy24 支払いデータは削除されません。既定：オフ。

注文手続き

支払いの手順で、購入者は支払い方法（既定は P24 のロゴが付いた Przelewy24）を選び、注文を確定します。モジュールは、カート合計金額をカートの通貨で Przelewy24 の取引として登録します。このとき、購入者のメールアドレス、氏名、請求先の国、およびカート番号とストア名を含む説明 Cart # も送信されます。支払いの試行ごとに、個別のセッション ID が割り当てられます。購入者は Przelewy24 の決済ページに移動し、BLIK、オンラインバンク振込、カード、または Przelewy24 アカウントで有効になっているその他の方法で支払いを行います。決済ページは、Przelewy24 が対応している場合は購入者のカートの言語で、それ以外は英語で表示されます。この時点では、まだ注文は存在しません。

注文が支払い済みになるのは、Przelewy24 が確認した後だけです。Przelewy24 は、署名付きの通知をストアに送信します。モジュールは、CRC キー、Merchant ID、POS ID で署名を確認し、そのセッションがこのカートについて同じモードで登録されたものであることを確認し、金額と通貨が支払い試行と現在のカート合計に一致することを確認します。その後にのみ、Przelewy24 で取引を検証し（Przelewy24 は検証済みの支払いのみを入金します）、Payment accepted の状態で注文を作成します。有効な署名のない webhook は拒否されます。

支払い後、購入者はストアに戻ります。通知がまだ届いていない場合、モジュールは認証されたサーバー間リクエストで Przelewy24 に取引のステータスを照会し（カートごとに 10 秒に 1 回まで）、同じ確認を適用します。戻りページだけで注文が支払い済みになることはありません。支払いが確定すると、購入者には標準の注文確認ページが表示されます。確定していない間は、Payment confirmation ページに 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: と表示され、Check again ボタンと、注文手続きを開く Pay again ボタンが表示されます。カートは保持され、同じカートの以前の Przelewy24 ページで後から行われた支払いも引き続き受け付けられます。注文が保留中の場合、確認ページには Your payment is being verified. We will send you an e-mail as soon as it is confirmed. と表示されます。

支払いを開始できない場合、購入者は注文手続きに留まり、短いメッセージが表示されます：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 に再送されません。購入者は注文確認ページに移動します。

本モジュールは、保存済みカードやワンクリック決済、サブスクリプションや定期決済には対応しておらず、注文手続きで P24 の支払い方法（BLIK コード入力欄など）を選択することもできません。分割払いウィジェットもなく、カートの内容を Przelewy24 に送信することもありません。

注文と返金

注文ステータス

No order yet: 購入者は Przelewy24 に移動したものの支払いを行っていないか、支払いがまだ確定していません。カートのみが存在します。

Payment accepted: 支払いが検証されました。支払いは、P24 の注文番号を取引 ID として記録され、メモには P24 の注文番号、金額、モードが表示されます。各支払いは一度だけ適用されます。

Przelewy24 payment on hold: Przelewy24 から報告された金額または通貨がカートと異なります（例えば、支払い開始後にカートが変更された場合）。支払いは確定されておらず、メモにその旨が記載されます。または、支払いが届き、キャンセル済みの注文に対して検証されました。注文は黙って再開されることはなく、メモには注文の発送または支払いの返金を求める内容が記載されます。Przelewy24 の管理画面で支払いを確認してください。不一致の後、保留中の注文に対して別の試行による正しい支払いが後から届いた場合、注文は Payment accepted に移動します。

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

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

Przelewy24 支払いブロック

注文ページには Przelewy24 payment ブロックが表示され、P24 の注文番号、セッション、環境（サンドボックスの支払いには Sandbox バッジ）、支払いステータスと検証方法（通知または戻り）、支払い済み金額と返金済み金額、返金フォーム、返金履歴、注文の Payment notes が含まれます。

返金

Przelewy24 payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Przelewy24 をクリックします。確認の質問 Refund this amount through Przelewy24? This cannot be undone. に同意してください。全額返金と一部返金に対応しており、まだ返金されていない金額までが対象です。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は、支払いが行われたモード（サンドボックスまたは本番）で送信されるため、そのモードのキーが設定されている必要があります。返金は、Przelewy24 が支払いを検証した後に利用できます。

Przelewy24 は返金を非同期で処理します。ブロックには Refund of … requested at Przelewy24. The result will be added as an order note. と表示され、返金履歴にはステータス requested が表示され、メモが追加されます。結果は後で通知 URL に届きます。ステータスは completed になり、メモ Przelewy24: refund of … completed. が追加されます。または rejected になり、お金が購入者に返金されなかったことを示すメモが追加されます。全額返金の場合、リクエスト時に注文が Refunded になります。一部返金ではステータスは変わりません。返金が拒否された場合は、Przelewy24 の管理画面で確認してください。注文ステータスは自動的に元に戻されません。

Przelewy24 が返金リクエストを受け付けない場合、ブロックには Przelewy24 refund failed: と理由が表示され、返金は記録されません。モジュールはクレジットスリップを作成しません。注文ページの標準的な PrestaShop の返金ボタンでは Przelewy24 を通じて返金されず、Przelewy24 の管理画面で直接行われた返金は注文に追加されません。

ライセンスキー

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

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

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

トラブルシューティング

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

支払いは完了したが、注文が作成されない: Przelewy24 からの通知がストアに届かず、購入者もストアに戻っていません。Notification URL がインターネットから到達可能であること（前段にファイアウォールや HTTP 認証がないこと）、そして支払いのモードの Merchant ID、POS ID、CRC キーが正しいことを確認してください。拒否された通知は、Debug Log がオフでもログに書き込まれます。モジュールのページにある Log 欄を確認してください。

ストアが通知にどう応答するか: 処理済み、繰り返し、または不明な通知には HTTP 200 で応答されます。それ以外の場合、Przelewy24 は後で再送します。400（データ欠落または不正な形式）、401 Invalid signature（CRC キーが誤っている、別の Merchant ID または POS ID）、401 Invalid signature for this payment（支払いとは別のモードのキーで署名された通知）、405（POST リクエストではない）、500 Verification failed（Przelewy24 での検証が失敗した。注文が存在する場合、注文に一度だけメモが追加される）、500 Order could not be created（例：モジュールが無効になっている。次の通知は、再検証なしで注文を作成する）、503 Busy, retry later（同じ瞬間に別のリクエストによってカートが確定処理中だった）。

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

支払い後に注文が Przelewy24 payment on hold になる: Przelewy24 payment ブロックのメモを確認してください。金額または通貨がカートと異なったか、キャンセル済みの注文に対して支払いが届きました。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.（本番の場合も同じ）は、支払いのモードのキーが削除されたことを意味します。キーを再入力してください。Invalid refund amount は、金額が空、数字ではない、またはまだ返金されていない金額を超えていることを意味します。

アンインストール

Modules > Module Manager に移動し、VibeFox Przelewy24 Payment の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の Przelewy24 支払いデータ（セッション、P24 注文番号、返金）と、注文ステータス Przelewy24 payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモと取引 ID を保持します。

Przelewy24 は、その所有者の商標です。本モジュールは Przelewy24 との提携や Przelewy24 による承認を受けていません。