VibeFox PayPlug for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 〜 9.x。

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

通貨と金額:ユーロ（EUR）、支払いごとに 0.99 〜 20,000.00。PayPlug の既定値です。カートの通貨が異なる場合、またはこの範囲外の場合は、支払い方法が表示されません。

PayPlug アカウント:PayPlug アカウントの秘密鍵が必要です。テスト用の鍵（sk_test_...）および／または本番用の鍵（sk_live_...）です。それ以外の鍵は不要で、PayPlug で通知を設定する必要もありません。通知を受け取るには、ショップがインターネットから到達可能である必要があります。そうでない場合、注文はお客様が PayPlug から戻ったときに作成されます。

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

インストール

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

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

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

4. PayPlug ポータルから秘密鍵を貼り付けます（設定を参照）。

5. Enable/Disable を有効にして Save をクリックします。Test Mode を有効にした状態で支払いをテストし、その後無効にして実際の支払いを受け付けます。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox PayPlug Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上部には、支払い方法が有効なのに現在のモードの秘密鍵が空の場合、またはショップの既定の通貨が EUR ではない場合に、警告が表示されます。どちらの場合も、支払い方法はチェックアウトで非表示になります。

チェックアウト

Enable/Disable: Enable PayPlug Gateway で支払い方法のオン／オフを切り替えます。既定値: off。

Title: チェックアウトでお客様に表示される支払い方法の名前です。注文に保存される支払い方法の名前でもあります。既定値: PayPlug。必須。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値: Pay securely by card via PayPlug。

API キー

秘密鍵は PayPlug ポータルの Developers > API keys にあります。このセクションにはポータルへのリンクがあります。

Test Mode: 新しい支払いにテスト用の秘密鍵を使用します。実際の支払いは処理されません。もう一方のモードで行われた支払いは、ステータス確認と返金のために、それぞれのモードの鍵を引き続き使用します。既定値: on。有効な間、お客様には支払い方法の下に Test mode: no real payment will be made. と表示されます。

Test Secret Key: PayPlug のテスト用秘密鍵です。sk_test_ で始まります。

Live Secret Key: PayPlug の本番用秘密鍵です。sk_live_ で始まります。

接頭辞が誤っているキーは保存されません。たとえば、ページには Test Secret Key must start with "sk_test_". The previous value was kept. と表示されます。保存済みのキーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

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

Notification URL: モジュールが支払いごとに PayPlug へ送信するアドレスです。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_payplug_gateway/webhook のような形式になります。PayPlug ポータルには何も入力する必要はありません。この URL はインターネットから到達可能である必要があります。そうでない場合、注文はお客様が PayPlug から戻ったときに作成されます。

注文

Order Status After Payment: 支払いが成功した後に設定される注文ステータスです。ステータスは直ちに設定され、2 回目のステータス変更は行われません。

Processing (default): 注文に PrestaShop のステータス Payment accepted が設定されます。

Completed: 支払い済みのすべての注文に Delivered のステータスが設定されます。

詳細設定

Logging: API 呼び出しと通知を、モジュールフォルダ内の logs/ppg_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。秘密鍵、カード情報、お客様データは決して記録されません。既定値: off。

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

Delete Data on Uninstall: 有効にすると、モジュールのアンインストール時にモジュールの設定とそのログが削除されます。注文に保存された PayPlug の決済 ID と、注文ステータス PayPlug payment on hold は保持されます。既定値: off。

チェックアウト

決済ステップで、お客様は支払い方法を選択します（既定では PayPlug のロゴが付いた PayPlug）。テストモードでは、この選択肢に Test mode: no real payment will be made. と表示されます。確定すると、モジュールはカートの合計金額（セント単位）で PayPlug の支払いを作成し、お客様を PayPlug の支払いページへ移動させます。請求先住所と配送先住所、メールアドレス、カートの言語は PayPlug に渡されます。お客様はそこでカード払いを行います。この時点ではまだ注文は存在しません。

支払い後、お客様はショップに戻ります。注文は PayPlug が確認した後にのみ支払い済みとしてマークされます。モジュールは、通知が届いたときと、お客様が戻ってきたときに、PayPlug API から支払いを読み取ります。その後注文が作成され、お客様には標準の注文確認ページが表示され、Your payment with PayPlug has been received. と案内されます。注文が保留中の場合、ページには We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. と表示されます。注文が Payment error の状態であるか、支払いなしでキャンセルされた場合、ページには Your PayPlug payment was not completed. Please contact us about this order. と表示されます。お客様の戻りの時点で PayPlug に問い合わせできなかった場合は、Payment confirmation ページに同じ「we are confirming」の文言と Check again ボタンが表示されます。通知が届いた時点で注文が作成されます。

お客様が PayPlug のページでキャンセルすると、支払いページは PayPlug 側で閉じられるため、後から誤って支払うことはできません。お客様はチェックアウトに戻り、次のいずれかのメッセージが表示されます：You cancelled the PayPlug payment. You can try again or choose another payment method.、The PayPlug payment session has expired. Please try again or choose another payment method.、The PayPlug payment failed. Please try again or choose another payment method.、または支払いが開いたままだった場合は Your PayPlug payment was not completed. You can try again or choose another payment method. カートは保持されます。

お客様が同じカートを再度支払う場合、モジュールはまず前回の試行を確認します。その間に支払い済みであれば、新たな支払いなしで注文が作成されます。同じ金額で依然として開いている場合は、同じ支払いページが再利用されます。そうでなければ、古いページは PayPlug 側で閉じられ、新しい支払いが作成されます。

PayPlug が支払いを開始できない場合、お客様はチェックアウトに留まり、「PayPlug could not accept your billing details (postcode). Please check them and try again.」や「The payment provider could not be reached. Please try again in a moment.」などの短いメッセージが表示されます。技術的な理由はログに記録されます。

通知は、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。

支払いは直ちに売上として確定されます。本モジュールには、Oney の分割払い、ワンクリックの保存済みカード、埋め込み型の決済フォーム、サブスクリプション、後日売上を確定する機能はありません。

注文と返金

注文ステータス

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

Payment accepted or Delivered: 支払いが確認されました。ステータスは Order Status After Payment に従います。支払いは PayPlug の決済 ID（pay_...）をトランザクション ID として記録され、備考には PayPlug の支払いとそのモードが表示されます。

PayPlug payment on hold: 支払われた金額または通貨がカートと異なる場合（備考 amount/currency mismatch。たとえば支払いの開始後にカートが変更された場合）、本番モードのショップでテスト支払いが行われたため、入金はなく支払いも記録されない場合、キャンセル済みの注文に対する支払いが届いた場合、または支払いが承認されたが売上確定されていない場合（PayPlug ポータルで売上を確定してください。PayPlug が支払い済みと報告すると、注文は支払い済みとしてマークされます）。備考には確認すべき内容が記載されます。

Payment error: 保留中の注文の承認済み支払いが失敗したか、キャンセルされました。

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

支払い済みのカートに対する 2 回目の試行も支払われた場合、注文は変更されません。備考で、PayPlug ポータルから重複した支払いを返金するよう求められます。支払い済み、キャンセル済み、または返金済みの注文は、後の通知によって再び開かれることはありません。

PayPlug 支払いブロック

注文ページには PayPlug payment ブロックが表示されます。PayPlug の決済 ID、支払いステータス、支払い済み金額と返金済み金額、テスト支払い用の Test mode バッジ、返金履歴、注文の PayPlug notes が含まれます。

返金

PayPlug payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via PayPlug をクリックします。Refund this amount through PayPlug? This cannot be undone. の確認に応答してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセスは必要ありません。返金は PayPlug が実際に請求した金額までです。そのため、金額の不一致が生じた場合は、注文合計ではなく、お客様が実際に支払った金額を返金できます。返金は注文を実際に支払った支払いに対して行われ、返金が行われたモード（テストまたは本番）の秘密鍵を使用します。そのため、そのモードの鍵が設定されている必要があります。PayPlug が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。返金が成功すると、PayPlug の返金 ID と理由を添えて、返金履歴と備考に追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。返金は、PayPlug が支払いを支払い済みと報告した後にのみ可能です。

モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop 返金ボタンは、PayPlug を経由して返金を行いません。

PayPlug ポータルで行われた返金は通知によって届き、備考に一度だけ追加されます。これらはブロックには集計されず、注文ステータスやクレジットスリップも変更しません。必要に応じて手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに PayPlug が表示されない:ライセンスが有効か、Enable/Disable がオンか、現在のモードに秘密鍵があるか（テストモードでは Test Secret Key、本番モードでは Live Secret Key）、カートの通貨が EUR か、カートの合計が 0.99 〜 20,000.00 EUR の範囲内かを確認してください。Payment > Preferences で、カートの通貨、お客様の国、お客様のグループに対してモジュールが許可されているかを確認してください。開発者は、フック actionWcpPayplugSupportedCurrencies と actionWcpPayplugAmountLimits で通貨と上限を変更できます（値はセント単位）。

支払いは完了したが注文が作成されない:通知がショップに届かず、お客様も戻っていません。設定に表示されている Notification URL で、ショップがインターネットから到達可能か確認してください。たとえば、ファイアウォールやパスワード保護によってブロックされていないかを確認します。Logging を有効にし、Log フィールドで拒否された通知を確認してください。

通知の応答が Verification failed. になる:PayPlug API から支払いを読み取れませんでした。たとえば、PayPlug が応答しなかった、または支払いのモードの秘密鍵が設定されていないなどの理由が考えられます。注文は変更されず、PayPlug は通知を再送します。

通知の応答が Temporarily unavailable. になる:お客様の戻りなど、別のリクエストによって同じ時点でカートが更新されていたか、注文を作成できませんでした（たとえばモジュールが無効になっている場合）。PayPlug は通知を再送します。ログに理由が表示されます。

通知の応答が Unknown payment. または Payment does not belong to the order. になる:その支払いはこのショップによって作成されていないか、このカートのためのものではありません。たとえば、同じ PayPlug アカウント上の別のショップの支払いです。無視されます。

ブラウザで通知 URL に Method not allowed. と表示される:これは正常です。この URL は PayPlug からのリクエストのみを受け付けます。

お客様が PayPlug を選択するとエラーが表示される:Logging を有効にして、Log フィールドを確認してください。誤ったキーの場合は This payment method is temporarily unavailable. Please choose another payment method. と表示されます。その他のメッセージでは、PayPlug に拒否された請求フィールドが示されます。

支払い後に注文が PayPlug payment on hold になる:PayPlug payment ブロックの備考（注文ステータスを参照）を確認してから、注文を処理するか支払いを返金してください。

モードに関するメッセージで返金が失敗する:支払いはテストモードまたは本番モードで行われましたが、そのモードの秘密鍵が設定されていません。キーを入力してから、もう一度お試しください。

Unexpected response from PayPlug. で返金が失敗する:PayPlug は有効な返金なしで応答しました。何も記録されていません。再試行する前に、PayPlug ポータルで返金を確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox PayPlug Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete Data on Uninstall が有効な場合、モジュールの設定とログは削除されます。無効な場合は、後で再インストールできるようにすべての設定が保持されます。PayPlug の支払いと返金の記録、および注文ステータス PayPlug payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いの備考とトランザクション ID を保持します。

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