VibeFox PayPlug for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP: 8.0 以降。

通貨と金額：ユーロ（EUR）、1 回の支払いあたり 0.99 〜 20,000.00。これは PayPlug の既定値です。ユーロは System > Localisation > Currencies で有効にし、購入者が選択できるようにしておく必要があります。チェックアウトの通貨が別の場合、またはこの範囲外の場合、その支払い方法は表示されません。

PayPlug アカウント：PayPlug アカウントのシークレットキーが必要です。テスト用キー（sk_test_...）および／または本番用キー（sk_live_...）です。他のキーは必要なく、PayPlug で通知を設定する必要もありません。通知を受け取るには、ストアがインターネットからアクセス可能である必要があります。アクセスできない場合、購入者が PayPlug から戻ったときに注文が確定します。

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

インストール

ダウンロードは、OpenCart の両バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ wcp_payplug_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_payplug_gateway.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両バージョンで共通です。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_payplug_gateway-oc3-(version).ocmod.zip を選択します。本拡張機能に OCMOD の変更はないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox PayPlug Gateway を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、決済拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

4. PayPlug のポータルからシークレットキーを貼り付けます（設定の項目を参照）。

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

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_payplug_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox PayPlug Gateway を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

4. OpenCart 3 の手順 3 〜 5 と同様に、ライセンスキーと PayPlug のシークレットキーを入力します。設定ページとそのフィールドは両バージョンで同じです。違うのは Notification URL だけです（通知を参照）。

新規インストール時は、支払い方法が無効、テストモードが有効の状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit。セクションは左側に並んでおり、一覧の下にある Save ボタンでページ全体を保存します。設定の上部には、支払い方法は有効なのに現在のモードのシークレットキーが空の場合、またはストアの既定の通貨が EUR でない場合に警告が表示されます。いずれの場合も、チェックアウトではその支払い方法は表示されません（既定の通貨が別の場合は、その通貨が選択されている間）。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時には、Title は 1 〜 128 文字、Sort Order は整数、Total は 0 以上の数値であり、注文ステータスが存在している必要があります。条件を満たさない場合は何も保存されず、ページにエラーが表示されます。形式の誤ったシークレットキーは保存されませんが、他の設定は保存されます。その場合、ページには Settings saved, except the secret key shown in red. と、たとえば Test Secret Key must start with "sk_test_". The previous value was kept. が表示されます。

Checkout

Enable/Disable：Enable PayPlug Gateway で支払い方法の有効・無効を切り替えます。既定値：無効。

Title：チェックアウトで購入者に表示される支払い方法の名前です。注文にも、この支払い方法の名前として保存されます。既定値：PayPlug。必須、128 文字以内。

Description：Confirm Order の手順で、確認ボタンの上に購入者へ表示されるテキストです。既定値：Pay securely by card via PayPlug.

Sort Order：チェックアウトの支払い方法の中で PayPlug が表示される位置です。空欄のままにするか、整数を入力してください。

Geo Zone：選択したジオゾーン内の支払い先住所に対してのみ PayPlug を提供します。既定値：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total：PayPlug を提供するために注文が達している必要がある、ストアの既定の通貨でのチェックアウト合計です。空欄にすると、どの金額でも PayPlug を提供します。PayPlug 自体は、1 回の支払いあたり 0.99 〜 20,000.00 EUR を受け付けます。

API キー

シークレットキーは、PayPlug のポータルの Developers > API keys にあります。このセクションにはポータルへのリンクがあります。

Test Mode：新しい支払いにテスト用のシークレットキーを使用します。実際の支払いは処理されません。もう一方のモードで行われた支払いは、ステータス確認と返金に、それぞれのモードのキーを使い続けます。既定値：有効。有効な間、購入者は Confirm Order の手順で Test mode: no real payment will be made. を見ます。

Test Secret Key：PayPlug のテスト用シークレットキーです。sk_test_ で始まります。

Live Secret Key：PayPlug の本番用シークレットキーです。sk_live_ で始まります。

保存されたキーは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。保存済みのキーを削除するには、フィールドの下にある Clear the saved key on save にチェックを入れ、Save をクリックします。

通知

Notification URL：拡張機能が支払いごとに PayPlug へ送信するアドレスです。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook、OpenCart 4 では https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook のような形式で、OpenCart をインストールしたストアのアドレスから自動的に作成されます。PayPlug のポータルで入力する必要はありません。各通知は、PayPlug API から支払いを読み直して確認されるため、購入者がストアに戻らなくても支払いは確定します。この URL はインターネットからアクセス可能である必要があります。アクセスできない場合、注文は購入者が PayPlug から戻ったときにのみ確定します。

注文

OpenCart は、Confirm Order の手順で、ステータスのない注文（欠落注文）を作成します。注文にステータスが付くのは、通知または購入者の戻りによって PayPlug が支払いを報告した後だけです。支払いは常に PayPlug から読み直されます。以下の各フィールドには、お使いの OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment：支払いが成功した後に設定されるステータスです（例：Processing、Complete）。既定値：Processing。

PayPlug Payment On Hold Status：支払いの確認が必要な場合に設定されるステータスです（注文ステータスを参照）。既定値：Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Payment Error Status：保留中の注文の承認済み支払いが失敗した、またはキャンセルされた場合のステータスです。既定値：Failed。

Refunded Status：注文ページから支払いを全額返金した後に設定されるステータスです。既定値：Refunded。

詳細設定

Logging：API の呼び出しと通知を、OpenCart のログフォルダ（storage/logs）にある ppg_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。シークレットキー、カード情報、購入者データは記録されません。既定値：無効。

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

Delete Data on Uninstall：有効にすると、拡張機能をアンインストールしたときに、拡張機能の設定とそのログが削除されます。注文の PayPlug の支払いと返金の記録は常に保持されます。既定値：無効。

インポート / エクスポート

Export：Download JSON で、設定を JSON ファイルとして保存します。シークレットキーはエクスポートされません。

Import：以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みのシークレットキーは保持されます。

チェックアウト

Payment Method の手順で、購入者は支払い方法を選択します（既定では PayPlug）。Confirm Order の手順では、購入者にあなたの説明文と、You will be redirected to the secure PayPlug payment page to pay by card. の案内が表示されます。テストモードの場合は、Test mode: no real payment will be made. も表示されます。OpenCart はこの手順で、まだステータスのない注文を作成します。OpenCart 4 では、購入者は Payment method options のウィンドウで、支払い方法ブロックの Choose ボタンから支払い方法を選択し、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は注文合計（セント単位）に対する PayPlug の支払いを作成し、購入者を PayPlug の支払いページに移動させます。請求先住所と配送先住所、メールアドレス、注文の言語が PayPlug に渡されます。購入者はそこでカード払いをします。

支払い後、購入者はストアに戻ります。注文が支払い済みとしてマークされるのは、PayPlug が確認した後だけです。拡張機能は、通知が届いたときと購入者が戻ったときに、PayPlug API から支払いを読み取ります。その後、注文は OpenCart の通常の方法でステータスを受け取り、通常の注文メールと在庫の更新が行われます。購入者には、OpenCart の注文完了ページが 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. と表示されます。注文が支払いエラーのステータスの場合、ページには Your PayPlug payment was not completed. Please contact us about this order. と表示されます。購入者が戻った時点で PayPlug に問い合わせできなかった場合は、Payment confirmation ページに同じ「確認中」の文言と 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. と表示されます。カートは保持されます。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。

OpenCart 3 は Confirm Order の手順が表示されるたびに新しい注文を作成し、OpenCart 4 は注文をチェックアウトで更新するため（新しい試行は同じ注文に対する新しい PayPlug 支払い）、拡張機能はまず同じカートの以前の試行を確認します。そのいずれかが、その間に支払い済みになっていた場合は、新たに支払いを作成せず、その支払いを使用して、購入者を成功ページに移動させます。今回の注文の試行が、同じ金額で開いたままであれば、同じ支払いページを再利用します。それ以外の場合は、古いページを PayPlug 側で閉じて、新しい支払いを作成します。閉じられたページに対する遅延した支払いも記録されます。カートの変更（新しい数量を含む）は、独自の支払いが必要な新しいカートとして扱われます。

OpenCart 4 では、成功ページが表示されるまで注文はチェックアウトに保持されます。その注文が支払いのないまま閉じられた場合（例：キャンセルした、または承認済みの支払いが失敗した）、購入者は Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. のメッセージとともにチェックアウトに戻されます。次の Confirm Order では新しい注文の支払いが行われます。その注文が以前のカートについてすでに支払い済みで、その後カートが変更されている場合、購入者はチェックアウトに戻され、次の Confirm Order では現在のカートの新しい注文の支払いが行われます。閉じられた注文が支払い済みとして表示されることはありません。

PayPlug が支払いを開始できない場合、購入者は Confirm Order の手順に留まり、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. などの短いメッセージが表示されます。技術的な理由はログに記録されます。

ストアがメンテナンスモードの間も、通知は機能します。OpenCart は決済拡張機能のリクエストを通過させるためです（OpenCart 4 では、拡張機能がこのための独自の起動アクションを追加し、購入者が PayPlug から戻る際も通過させます）。

支払いは直ちに決済されます。本拡張機能には、Oney 分割払い、ワンクリック保存カード、埋め込み型の決済フォーム、定期購入、後日決済は含まれません。

注文と返金

注文ステータス

ステータスなし（欠落注文）：購入者は PayPlug に移動したものの、まだ支払っていないか、PayPlug がまだ支払いを確認していません。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。支払いが失敗した場合、その試行は閉じられ、購入者は再度支払うことができます。

Order Status After Payment（既定値 Processing）：支払いが確認されました。メモには PayPlug の支払いとそのモードが表示されます。

PayPlug Payment On Hold Status（既定値 Pending）：支払われた金額または通貨が注文と一致しない（メモ amount/currency mismatch）、ストアが本番モードの間にテスト支払いが行われたため実際の入金がない、注文がすでに別のステータス（キャンセルされたなど）になった後に支払いが届いた、または支払いは承認済みだが未キャプチャである（PayPlug のポータルでキャプチャしてください。PayPlug が支払い済みと報告すると、注文は支払い済みとしてマークされます）。メモには確認すべき内容が記載されます。

Payment Error Status（既定値 Failed）：保留中の注文の承認済み支払いが失敗した、またはキャンセルされた状態です。OpenCart はこの変更を購入者に通知します。

Refunded Status（既定値 Refunded）：拡張機能を通じて支払いが全額返金された状態です。

すでに支払い済みのカートの別の注文も支払われた場合、その注文はステータスなしのままとなり、支払い済みの注文は変更されません。支払い済みの注文に付くメモでは、PayPlug のポータルで重複した支払いを返金するよう求められます。支払い済みまたは返金済みの注文は、後からの通知によって再度開かれることはありません。

メモは、購入者には表示されない注文の History のエントリです。

VibeFox PayPlug Gateway タブ

Sales > Orders で、PayPlug で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox PayPlug Gateway タブには、PayPlug payment ID（テストの支払いには Test mode のラベル付き）、支払いの Status、Paid / refunded の金額、返金フォーム、返金履歴（各返金のモードを含む）、そして注文の PayPlug notes が表示されます。このタブは、拡張機能にアクセス権を持つユーザーに表示されます。

返金

VibeFox PayPlug Gateway タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via PayPlug をクリックします。Refund this amount through PayPlug? This cannot be undone. の確認に応じてください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金は、PayPlug が実際に請求した金額までしか行えないため、金額の不一致があった場合は、注文合計ではなく購入者が支払った金額を返金することになります。返金は、注文を実際に支払った支払いに対して、返金が行われたモード（テストまたは本番）のシークレットキーを使って処理されます。そのため、そのモードのキーが設定されている必要があります。PayPlug が返金を受け付けない場合、タブにエラーが表示され、返金は記録されません。返金が成功すると、PayPlug の返金 ID と理由とともに、返金履歴とメモに追加されます。全額返金を行うと、購入者に通知されず、商品も在庫に戻されずに、注文に Refunded Status が設定されます。これは手動でのステータス変更と同様です。一部返金ではステータスは変わりません。返金は、PayPlug が支払いを支払い済みと報告した後に利用できます。

Sales > Returns での商品返品では、PayPlug を通じて返金は行われません。

PayPlug のポータルで行われた返金は、通知によって届き、メモには一度だけ追加されます。返金履歴には表示されますが、拡張機能による返金としてはカウントされず、注文のステータスも変更されません。必要に応じて手動で記録してください。

ライセンスキー

本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox PayPlug Gateway は、Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（ライセンスの有効期限日やドメインなど）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-payment-payplug の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、本拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

キーが承認されない場合、ブロックにその理由が表示されます（例：Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付）。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できたステータスで動作を続けます。

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

有効なキーがない場合、PayPlug はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) の表示付きで見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合、支払い方法はすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間は非表示になります。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も機能します。

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

トラブルシューティング

チェックアウトに PayPlug が表示されない：ライセンスが有効であること、Enable/Disable が有効であること、現在のモードにシークレットキーがあること（テストモードでは Test Secret Key、本番モードでは Live Secret Key）、チェックアウトの通貨が EUR であること、注文金額が 0.99 〜 20,000.00 EUR の範囲内であることを確認してください。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。開発者は、OpenCart のイベント ppg_supported_currencies と ppg_amount_limits（セント単位の値）で通貨と上限を変更でき、ppg_payment_data で支払いリクエストを変更できます。

支払いは完了したが、注文にステータスが付かない：通知がストアに届かず、購入者も戻っていません。設定に表示されている 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 からのリクエストのみを受け付けます。

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

購入者が戻ると Payment verification failed. と表示される：戻りリンクが、その注文のどの支払い試行とも一致しません。たとえば、別のブラウザで開かれた場合です。PayPlug のポータルで支払いを確認してください。注文のステータスは、通知によって設定されます。

支払い後に注文が保留中になる：VibeFox PayPlug Gateway タブのメモを確認し（注文ステータスを参照）、その後で注文を処理するか、支払いを返金してください。

タブに返金フォームがない：タブに理由が表示されます。支払いがまだ支払い済みでない、全額返金されている、ユーザーグループに拡張機能を変更する権限がない、または支払いのモードのシークレットキーが設定されていない、のいずれかです。

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

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox PayPlug Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します。Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントと、メンテナンスモードでも通知と購入者の戻りを通過させる起動アクションも削除されます）。Delete Data on Uninstall が有効な場合は、その他の設定（タイトル、説明、テストモード、シークレットキー、ログ）とログが削除されます。無効な場合は、後で再インストールする際のために保持されます。PayPlug の支払いと返金の記録は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、支払いメモを保持します。

OpenCart 4 では、拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧にある VibeFox PayPlug Gateway の Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するため Delete（赤いゴミ箱のボタン）をクリックします。

PayPlug は、それぞれの所有者の商標です。本拡張機能は PayPlug と提携しておらず、PayPlug による推奨もありません。