VibeFox Quickpay for WooCommerce — ヘルプ

要件

WordPress: 6.2 以降。

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

PHP: 8.0 以降。

Quickpay アカウント: Quickpay マネージャーから 2 つの値が必要です。API ユーザーの API キー（支払いの作成、キャプチャ、返金に使用）と、アカウントの秘密キー（Quickpay コールバックの署名を検証するために使用）です。Quickpay 側で他に設定する必要はありません。Quickpay のコールバックを受け取れるよう、サイトはインターネットから到達可能である必要があります。パスワード保護やメンテナンスモードであってはいけません。

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

インストール

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

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

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

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

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

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

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Quickpay。API キーと秘密キーの両方が入力されるまで、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 ユーザーの API キー（Settings > Users）と、アカウントの秘密キーをコピーします。このセクションには、ストアのコールバック URL も表示されます。URL の形式は https://your-site/wc-api/qpg_quickpay/ です。この URL はすべての支払いで自動的に送信されるため、Quickpay で設定する必要はありません。

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

フィールドの下にある Test API key ボタンは、フィールドに入力されたキー（フィールドが空の場合は保存済みのキー）を、Quickpay への認証付きリクエストで確認します。結果は Connection successful — the API key is valid.、Quickpay rejected the API key.、API key is not configured. のいずれか、または Connection failed: に理由が続く形で表示されます。

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

Test payments: Accept payments made with Quickpay test cards。Quickpay には独立したサンドボックスはありません。Quickpay アカウントがテストモードの間、支払いはテストカードで行われ、テストとしてマークされます。テスト中のみオンにしてください。オフの場合、テスト支払いによって注文が支払い済みになることはなく、代わりに注文に備考が付きます。オンの場合、チェックアウトに Test mode: Quickpay test cards are accepted. と表示されます。デフォルト: オフ。

支払い

Capture: カードから代金が引き落とされるタイミング。

Order status after payment: Quickpay がキャプチャ済みの支払いを確認した後の注文ステータスです。ステータスは一度に設定され、ステータス変更は 1 回、メールは 1 セットだけ送信されます。

詳細設定

Debug log: Enable logging。ログは WooCommerce > Status > Logs にあり、ソースは wcp_quickpay_gateway です。拒否されたコールバックや Quickpay API のエラーなど、エラーと警告は常に記録されます。オンにすると、すべてのリクエストとコールバックも記録されます。API キー、カード情報、顧客情報は記録されることはありません。デフォルト: オフ。

Delete data: Delete the gateway settings and logs when the plugin is deleted。プラグインを無効化しても、何も削除されることはありません。注文データ（Quickpay の支払い ID、備考）は常に保持されます。デフォルト: オフ。

チェックアウト

購入者が支払い方法を選択し（デフォルトは Quickpay。Visa と Mastercard のアイコン付きで表示されます）、注文を確定します。プラグインは、注文の通貨で注文用の Quickpay 支払いを作成し、注文合計金額の支払いリンクを作成して、購入者を Quickpay の決済画面に移動させます。購入者は、Quickpay の決済画面で有効になっている方法のいずれかで支払います。請求先メールアドレスは Quickpay に渡されます。Quickpay が対応している場合、決済画面はストアの言語で表示されます（デンマーク語、ドイツ語、英語、スペイン語、フィンランド語、フランス語、イタリア語、オランダ語、ノルウェー語、ポーランド語、スウェーデン語）。それ以外の場合は英語で表示されます。

支払い後、購入者はストアの注文受付ページに戻ります。戻っただけでは、何も支払い済みにはなりません。注文は、Quickpay が署名付きコールバックで確認し、金額と通貨が注文と一致した場合にのみ支払い済みになります。Authorize only の場合、注文は代わりに保留になり、支払いは後でキャプチャします。

チェックアウト中に購入者が決済画面でキャンセルした場合、未払いの注文は WooCommerce の標準的な方法でキャンセルされ、カートは復元されます。Pay for order ページでキャンセルした場合、購入者はそのページに戻るため、注文は支払い可能な状態のままです。失敗またはキャンセルされた支払いは再試行できます。新しい試行では、注文の既存の Quickpay 支払いが新しいリンクで再利用されるため、古いリンクで並行して支払いが行われることはありません。未払いの注文がキャンセルされた場合、その支払いリンクは Quickpay で削除されます。

支払いを開始できない場合、購入者には The Quickpay payment could not be started. Please try again or choose another payment method. と表示されます。技術的な理由は注文の備考とログに追加されます。キーが設定されていない場合、購入者には Quickpay is not available at the moment. Please choose another payment method. と表示されます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

本プラグインは 1 回限りの支払いのみに対応しています。サブスクリプションや定期支払い、保存済みカード、支払い手数料には対応しておらず、カートや請求明細は Quickpay に送信されません。また、個別の MobilePay、Apple Pay、Klarna の方法はありません。購入者は Quickpay の決済画面で有効になっている方法から選択します。

注文と返金

注文ステータス

Pending payment: 購入者は Quickpay に移動しましたが、まだ支払っていません。自動キャプチャの場合、キャプチャ待ちの承認済み支払いが注文に記録されます。

Processing or Completed: Quickpay が、正しい金額と通貨でキャプチャ済みの支払いを確認しました。ステータスは Order status after payment に従います。注文の備考には Quickpay の支払い ID が表示され（テスト支払いの場合は TEST と表示）、注文のトランザクション ID として保存されます。

On hold: 支払いは承認のみで、Capture Quickpay payment を待っています。または、Quickpay が注文合計と異なる金額または通貨を報告しました（例: 支払いの開始後に注文が編集された、または Quickpay マネージャーで別の金額がキャプチャされた）。または、キャプチャに失敗し、金額はまだ確保されているだけです。注文の備考で説明されます。注文がすでに保留になっていた場合も同様です。

Failed: 支払いの試行が拒否されました。購入者は再度支払うことができます。

Cancelled: 購入者が決済画面でキャンセルした、ストアにより注文がキャンセルされた、WooCommerce の在庫保持タイムアウトによって注文がキャンセルされた、または Quickpay マネージャーで支払いがキャンセルされた、のいずれかです。

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

キャプチャ

Authorize only の場合、注文を開き、注文アクションで Capture Quickpay payment を選び、更新ボタンをクリックします。注文の合計金額がキャプチャされます。部分キャプチャは利用できません。Quickpay がすぐに確認すると、注文は支払い済みになります。そうでない場合は、キャプチャが要求されたことが備考に表示され、Quickpay コールバックで確認された時点で注文は支払い済みになります。拒否されたキャプチャは注文画面に表示され、注文の備考に記録されます。

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

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Quickpay をクリックします。キャプチャ済みの支払いについては、全額返金と一部返金に対応しています。Quickpay は返金を非同期で処理します。備考には返金が要求されたことが表示され、コールバックによって最終結果（confirmed または理由付きの FAILED）が追加されます。Quickpay が返金をすぐに拒否した場合、WooCommerce がエラーを表示し、返金は記録されません。一度もキャプチャされていない承認済みの支払いは返金できません。その場合は Quickpay マネージャーでキャンセルしてください。

Quickpay マネージャーで直接行われた支払いと返金は、注文に備考として記録されるだけです。WooCommerce の返金として自動的に記録されることはありません。必要な場合は、Refund via Quickpay を使わずに WooCommerce で手動返金を作成してください。

ライセンスキー

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

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

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

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

トラブルシューティング

Quickpay がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、API key と Private key の両方が入力されていることを確認してください。両方のキーがないと、支払い方法は非表示になります。

支払いは完了したが、注文が Pending payment のまま: Quickpay のコールバックがストアに届かなかったか、拒否されました。サイトがインターネットから到達可能であること（パスワード保護やメンテナンスモードではないこと）と、Private key が同じ Quickpay アカウントの秘密キーであることを確認してください。拒否されたコールバックは、常に WooCommerce > Status > Logs に、ソース wcp_quickpay_gateway として記録されます。すべてのコールバックを確認するには、Debug log をオンにしてください。

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

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

ログに Callback: no order found for payment … と表示される: このコールバックは、このストアのどの注文も認識していない Quickpay の支払いに属しています。例えば、WooCommerce の外で作成された支払い、または削除された注文の支払いです。

ログに Callback: order #… is locked by another request. と表示される: 同じ注文の別のコールバックがその時点で適用されていました。このコールバックにはエラーが返されるため、処理済みとは見なされません。注文が変わらない場合は、Quickpay マネージャーで支払いを確認してください。

テスト支払いで注文が支払い済みにならなかった: Test payments がオフです。注文の備考には、テスト支払いが受け付けられなかったと表示されます。テスト中はこの設定をオンにし、アカウントを本番運用に移行したらオフにしてください。

支払い後に注文が On hold になっている: 注文の備考を確認してください。支払いは承認のみで Capture Quickpay payment を待っている可能性があります。支払われた金額や通貨が注文と異なる可能性もあります。キャプチャが失敗した可能性もあります。Quickpay マネージャーでキャプチャ、注文の処理、または支払いの返金を行ってください。

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

購入者に The Quickpay payment could not be started. と表示される: 注文の備考かログを開いてください。備考には Quickpay のエラーが表示されます。例えば、お使いの Quickpay アカウントが受け付けない通貨などです。

返金が失敗する: 注文には、キャプチャ済みの Quickpay 支払いが必要です。The Quickpay payment of this order has not been captured — there is nothing to refund. というメッセージは、支払いが承認のみであることを意味します。代わりに Quickpay マネージャーでキャンセルしてください。

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

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とプラグインのログ（ローテーションされたものを含むログファイルと、データベースのログエントリ）は、Delete data がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールする際のために残ります。既存の注文は、支払いの備考とトランザクション ID を保持します。

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