VibeFox Quickpay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールをインストールできません。

Quickpay アカウント: Quickpay マネージャーから 2 つの値が必要です。API ユーザーの API キー（支払いの作成、決済、返金に使用）と、アカウントの秘密キー（Quickpay コールバックの署名を検証するために使用）です。Quickpay で他に設定する必要はありません。Quickpay コールバックを受信できるように、ショップはパスワード保護なしでインターネットからアクセスできる必要があります。

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

インストール

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

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

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

4. Quickpay マネージャーから API キーと秘密キーを貼り付け、Test API key をクリックします（設定を参照）。

5. 決済方法と支払い後の注文ステータスを選択し、Enable/Disable をオンにして Save をクリックします。Quickpay アカウントがテストモードの間は、Test payments をオンにして、Quickpay のテストカードで支払いを行います。

インストール時に、モジュールは注文ステータス Quickpay payment on hold を 1 つ作成します。PrestaShop は、新しい支払いモジュールをすべての通貨、国、顧客グループに対して有効にします。このモジュールは、インストール時に有効になっている国に紐付けられます。すべての設定は Payment > Preferences で変更できます。

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Quickpay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。API キーと秘密キーの両方が保存されるまで、ページには Quickpay の設定が必要です: API キーと秘密キーを入力してください。両方が保存されるまで、決済時に支払い方法は表示されません。 と表示されます。Test payments がオンの間は、Quickpay アカウントを本番運用に切り替えるときにオフにするよう、ページに表示されます。

Quickpay

Enable/Disable: Enable Quickpay で支払い方法のオン/オフを切り替えます。デフォルト: オフ。

Title: 決済時に顧客に表示される支払い方法の名前です。注文に保存される支払い方法の名前にもなります。デフォルト: Quickpay。必須: 空のタイトルは保存されません。

Description: 決済時に支払い方法の下に表示されるテキストです。デフォルト: Pay securely by card or MobilePay on the Quickpay payment page.

Quickpay API 認証情報

Quickpay マネージャー（manage.quickpay.net）で Settings > Integration を開きます。API ユーザー（Settings > Users）の API キーと、アカウントの秘密キーをコピーします。

Callback URL: ショップのコールバック URL を表示します。フレンドリー URL を使用している場合は、次のような形式です: https://your-shop/module/wcp_quickpay_gateway/callback。Quickpay は支払いの操作（承認、決済、返金、キャンセル）が行われるたびにこの URL を呼び出します。すべての支払いに自動的に送信されるため、Quickpay で設定する必要はありません。

API key: Quickpay API ユーザーの API キーです。支払いの作成、決済、返金に使用されます。

Private key: アカウントの秘密キーです。Quickpay コールバックの署名（HMAC-SHA256）を検証するために使用されます。これがないと支払いを確認できず、コールバックは拒否されます。

保存されたキーは再び表示されません。フィールドは空のままで、保存済み — 空のままにすると保持されます。 と表示されます。変更する場合にのみ新しい値を入力してください。

保存済みの秘密情報を削除: API key または Private key にチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存されている値が保持されます。

Test payments: Quickpay のテストカードで行われた支払いを受け付けます。Quickpay には独立したサンドボックスがありません。Quickpay アカウントがテストモードの間、支払いはテストカードで行われ、テストとして表示されます。テスト中のみオンにしてください。オフの場合、テスト支払いによって注文が支払い済みになることはありません。オンの場合、決済画面の支払い方法の下に テストモード: Quickpay のテストカードを受け付けています。 と表示されます。デフォルト: オフ。

Test API key: このボタンは、API key フィールドに入力されたキー（フィールドが空の場合は保存済みのキー）を、認証付きのリクエストで Quickpay に対して確認します。保存はしません。結果として、接続成功 — API キーは有効です。、Quickpay が API キーを拒否しました。、API キーが設定されていません。、または 接続に失敗しました: と理由が表示されます。

支払い

Capture: カードから代金を引き落とすタイミングです。

Order status after payment: Quickpay が決済済みの支払いを確認した後の注文ステータスです。

詳細設定

Debug log: モジュールフォルダー内の logs/qpg_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。拒否されたコールバックや Quickpay API のエラーなど、エラーと警告は常に記録されます。オンにすると、すべてのリクエストとコールバックの詳細も記録されます。API キー、カード情報、顧客情報は記録されることはありません。デフォルト: オフ。

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

Delete data: オンの場合、モジュールをアンインストールするとゲートウェイの設定とログが削除されます。注文データ（Quickpay の支払い、返金、備考）と注文ステータス Quickpay payment on hold は常に保持されます。デフォルト: オフ。

チェックアウト

支払いの手順で、お客様は支払い方法（デフォルトは Quickpay、カードアイコン付き）を選んで確定します。モジュールは、カートの通貨でカートの Quickpay 支払いを作成し、カートの合計金額に対する支払いリンクを作成して、お客様を Quickpay の決済画面に移動させます。この時点ではまだ注文は存在しません。お客様は、Quickpay の決済画面で有効になっている支払い方法のいずれかで支払います。お客様のメールアドレスは Quickpay に渡されます。Quickpay が対応している場合、決済画面はお客様の言語で開きます（デンマーク語、ドイツ語、英語、スペイン語、フィンランド語、フランス語、イタリア語、オランダ語、ノルウェー語、ポーランド語、スウェーデン語）。それ以外の場合は英語で開きます。

支払い後、お客様はショップに戻ります。戻っただけでは、何も支払い済みにはなりません。注文は、Quickpay が確認した後にのみ支払い済みになります。決済された金額と通貨がカートと一致すると、署名付きコールバックによって注文が作成されます。その後、お客様には標準の注文確認ページが表示されます。Authorize only の場合は、代わりに注文が Quickpay payment on hold で作成され、支払いは後から決済します。お客様が戻ったときにコールバックがまだ届いていない場合、Payment confirmation ページに Quickpay によりお支払いを確認中です。注文が確認され次第、メールをお送りします。 と表示され、Check again と Back to checkout のボタンが表示されます。

お客様が支払い画面でキャンセルした場合、支払いリンクは Quickpay で削除され、お客様は お支払いはキャンセルされました。もう一度お試しいただくか、別の支払い方法をお選びください。 というメッセージとともに決済画面に戻ります。カードが拒否された場合のメッセージは お支払いは完了しませんでした。もう一度お試しいただくか、別の支払い方法をお選びください。 です。カートは保持されます。新しい試行では、新しいリンクでカートの Quickpay 支払いが再利用されるため、古いリンクが並行して支払われることはありません。カートの支払いが承認され決済を待っている間は、2 回目の支払いは開始されず、お客様には Payment confirmation ページが表示されます。

支払いを開始できない場合、お客様は Quickpay の支払いを開始できませんでした。もう一度お試しいただくか、別の支払い方法をお選びください。 というメッセージとともに決済画面に残ります。技術的な理由はログに書き込まれます。キーが不足している場合のメッセージは Quickpay は現在ご利用いただけません。別の支払い方法をお選びください。 です。

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

本モジュールは 1 回限りの支払いのみに対応しています。サブスクリプションや定期支払い、カードの保存、部分決済には対応しておらず、カートや請求書の明細は Quickpay に送信されません。また、個別の MobilePay、Apple Pay、Klarna の方法はありません。お客様は Quickpay の決済画面で有効になっている方法の中から選択します。

注文と返金

注文ステータス

No order yet: お客様は Quickpay に移動しましたが、支払いをしていない、カードが拒否された、または支払いが承認され自動決済を待っています。カートのみが存在します。

Payment accepted or Delivered: Quickpay が、正しい金額と通貨で決済された支払いを確認しました。ステータスは Order status after payment に従います。支払いは、取引 ID として Quickpay の支払い ID と共に記録され、備考に支払いが表示されます（テスト支払いには TEST と表示されます）。

Quickpay payment on hold: 支払いは承認のみで、Capture Quickpay payment を待っています。または、Quickpay が注文合計と異なる金額または通貨を報告しました（例: 支払いの開始後にカートが変更された、または Quickpay マネージャーで別の金額が決済された）。または、自動決済が失敗し、金額はまだ仮押さえのみです。備考に理由が説明されています。異なる金額で代金が決済された場合、支払いは Quickpay が決済した金額で注文に記録されます。

Canceled: 注文をキャンセルした、または保留中の注文の支払いが Quickpay マネージャーでキャンセルされた場合です。

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

すでに支払い済み、キャンセル済み、または返金済みの注文に対して支払いが届いても、注文は変更されません。二重払いを返金するなどのために、Quickpay マネージャーで支払いを確認するよう備考に表示されます。

未払いの注文をキャンセルすると、その支払いリンクは Quickpay で削除されます。承認済みの注文をキャンセルしても、仮押さえされた金額は自動的には解放されません。備考で、Quickpay マネージャーで支払いをキャンセルするよう通知されます。そうしない場合、仮押さえは承認の期限切れで終了します。

Quickpay ブロック

注文ページには、Quickpay payment ブロックが表示されます。支払い ID、支払いステータス、金額と返金済み金額、テスト支払い用の Test payment バッジ、カートのすべての Quickpay 支払いの一覧（複数ある場合）、返金履歴、注文の Quickpay notes が含まれます。決済と返金には注文を編集する権限が必要です。モジュールのページへのアクセスは必要ありません。

決済

Authorize only の場合は、Quickpay ブロックで Capture Quickpay payment をクリックし、Quickpay で注文合計を決済しますか？ を確認します。注文合計が決済されます。一部決済は利用できません。Quickpay が直ちに確認した場合、注文は Order status after payment のステータスに設定されます。そうでない場合、決済がリクエストされたことが備考に表示され、Quickpay のコールバックが確認した時点で注文が支払い済みになります。拒否された決済はブロックに表示され、注文に備考として記録されます。

返金

Quickpay ブロックに金額を入力します（まだ返金されていない金額が自動入力されます）。任意で理由を入力し、Refund via Quickpay をクリックします。この金額を Quickpay で返金しますか？この操作は取り消せません。 という確認に答えます。決済済みの支払いに対しては、全額返金と一部返金に対応しています。返金は Quickpay が決済した金額と通貨で行われるため、金額や通貨に不一致があった場合は、注文合計ではなく、お客様が実際に支払った金額まで返金できます。Quickpay は返金を非同期に処理します。返金履歴には requested と表示され、コールバックによって confirmed または failed に更新され、結果が備考に追加されます。Quickpay が返金を直ちに拒否した場合、ブロックにエラーが表示され、返金は記録されません。全額返金を行うと注文は Refunded になります。一部返金ではステータスは変わりません。一度も決済されていない承認済みの支払いは返金できません。その場合は Quickpay マネージャーでキャンセルしてください。

モジュールはクレジットスリップを作成しません。注文ページにある標準の PrestaShop の返金ボタンでは、Quickpay を通じて返金されません。

Quickpay マネージャーで直接行われた返金は、備考に追加されるだけです。注文ステータスとクレジットスリップは自動的には変更されません。必要に応じて手動で更新してください。

ライセンスキー

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

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

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

トラブルシューティング

決済時に Quickpay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、API key と Private key の両方が保存されていることを確認してください。両方のキーがないと支払い方法は表示されません。Payment > Preferences で、カートの通貨、お客様の国、お客様のグループに対してモジュールが許可されているか確認してください。

支払いは完了したが注文が作成されない: Quickpay コールバックがショップに届かなかった、または拒否されました。ショップがインターネットからアクセス可能であること（パスワード保護がないこと）、Private key が同じ Quickpay アカウントの秘密キーであることを確認してください。拒否されたコールバックは、常にモジュールのページのログに書き込まれます。すべてのコールバックを確認するには、Debug log をオンにしてください。

ログに Callback rejected: invalid checksum. と表示される: 設定の秘密キーが、コールバックを送信したアカウントのものではありません。Quickpay マネージャーの Settings > Integration から再度コピーしてください。

ログに Callback rejected: the private key is not configured. と表示される: 秘密キーを入力してください。秘密キーがない場合、コールバックは決して受け付けられません。

ログに Callback: no cart found for payment … と表示される: このコールバックは、このショップが作成したものではない Quickpay の支払いに関連しています。たとえば、PrestaShop の外で行われた支払いです。

ログに Could not lock the cart または Cannot create the order と表示される: その時点で、同じカートの別のコールバックが適用中だったか、注文を作成できませんでした（たとえば、モジュールが無効になっている場合）。コールバックにはエラーが返されるため、Quickpay はコールバックを再送します。

テスト支払いで注文が支払い済みにならなかった: Test payments がオフになっています。ログ（注文が存在する場合は備考も）に、テスト支払いが承認されなかったと表示されます。テスト中はこの設定をオンにし、アカウントが本番運用になったらオフにしてください。

支払い後に注文が Quickpay payment on hold になる: Quickpay ブロックの備考を確認してください。支払いは承認のみで Capture Quickpay payment を待っているか、支払われた金額または通貨が注文と異なるか、決済に失敗した可能性があります。決済する、注文を処理する、または支払いを返金してください。

Test API key に「Quickpay が API キーを拒否しました。」と表示される: キーが間違っているか、API にアクセスできないユーザーのものです。Quickpay マネージャーから API ユーザーの API キーをコピーしてください。

お客様に「Quickpay の支払いを開始できませんでした。」と表示される: モジュールのページにある Log フィールドを確認してください。Quickpay のエラーが表示されます。たとえば、Quickpay アカウントが受け付けない通貨などです。

返金に失敗する: 注文には決済済みの Quickpay 支払いが必要です。この注文の Quickpay 支払いは決済されていないため、返金するものがありません。 というメッセージは、支払いが承認のみであることを意味します。Quickpay マネージャーで決済するか、キャンセルしてください。返金額が無効です。最大 … は、金額が決済済みの支払いの残額を超えていることを意味します。

開発者は、フック actionQpgQuickpayLinkData で Quickpay の支払いリンクのパラメーターを変更できます。

アンインストール

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

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