VibeFox Autopay for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP: 8.0 以降。
Autopay サービス: Autopay サービスの Service ID と Shared key（ハッシュキー）が必要です。これらは Autopay の加盟店ポータルに表示されます。本番は portal.autopay.eu、テストは testportal.autopay.eu です。テストサービスには専用の Service ID と Shared key があります。Autopay に依頼して作成してもらってください。サービスのハッシュ関数は SHA-256 である必要があります。
通貨: 注文通貨は PLN、EUR、GBP、USD、CZK のいずれかで、かつご利用の Autopay サービスで受け付けられている必要があります。
到達可能なストア: Autopay がストアに通知を送信できる必要があるため、ストアはベーシック認証なしで、かつ POST リクエストをブロックするファイアウォールなしで、インターネットから到達可能でなければなりません。OpenCart は決済拡張機能のリクエストを通過させるため、メンテナンスモードでも通知はブロックされません。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。このファイルには README.txt、OpenCart 3 用のパッケージ wcp_autopay_payment-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_autopay_payment.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_autopay_payment-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、アーカイブ内の upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。
2. Extensions > Extensions に移動し、種類で Payments を選択します。VibeFox Autopay Payment を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、支払い拡張機能の一覧を変更する権限が必要です。
3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. Service ID と Shared key（テストと本番）を入力し、サービスの通貨を選択します。
5. Autopay ポータルで、サービスの ITN URL、戻り先 URL、SHA-256 ハッシュ関数を設定します（設定を参照）。
6. Enable/Disable をオンにして、Save をクリックします。テストモードでテスト注文を行い、その後、実際の支払いを受け付けるために Test mode をオフにします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_autopay_payment.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横にある Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、種類で Payments を選択します。VibeFox Autopay Payment を見つけて Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆ボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 3 ～ 6 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。ITN と戻り先のアドレスのみが異なります（ITN と戻り先のアドレスを参照）。
新規インストール直後は、支払い方法がオフ、テストモードがオン、通貨は PLN のみの状態で始まります。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体を保存します。設定の上には、選択した環境の Service ID または Shared key が空の場合（この場合、チェックアウトでは支払い方法が表示されません）、ストアの既定の通貨が Currencies で選択されていない場合（この場合、その通貨では支払い方法が表示されません）に警告が表示されます。テストモードがオンの間は、Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. と表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。
保存する際、Title は 1 ～ 128 文字である必要があり、Sort Order は整数である必要があり、Total は 0 以上の数値である必要があり、Service ID は英数字、ハイフン、アンダースコアのみで構成されている必要があります。いずれかの項目に誤りがある場合は、何も保存されず、ページに該当する項目が表示されます。
Autopay
Enable/Disable: Enable Autopay payment gateway は、支払い方法をオンまたはオフにします。既定値：オフ。
Title: チェックアウトでお客様に表示される支払い方法の名前です。注文に保存される支払い方法の名前にもなります。既定値：Autopay。必須。128 文字まで。
Description: Confirm Order のステップで、確認ボタンの上にお客様に表示されるテキストです。既定値：Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.
Sort Order: チェックアウトにおける支払い方法の中での Autopay の表示順です。空欄にするか、整数を入力します。
Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ Autopay を表示します。既定値：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。
Total: Autopay が表示されるために注文が満たす必要がある、ストアの既定の通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも Autopay が表示されます。
Autopay サービス
Service ID と Shared key は Autopay の加盟店ポータル（portal.autopay.eu または testportal.autopay.eu。このセクションからリンクされています）に表示されます。
Test mode: Autopay のテスト環境（testpay.autopay.eu）と、以下のテスト用認証情報を使用します。既定値：オン。オフにすると、本番用認証情報を使って pay.autopay.eu で実際の支払いを受け付けます。オンの間、お客様は Confirm Order のステップで Test mode: no real payment is taken. と表示されます。
Service ID (production): portal.autopay.eu に記載されている数値のサービス識別子です。
Shared key (production): 本番サービスのハッシュキーです。秘密にしてください。
Service ID (test): testportal.autopay.eu に記載されている数値のサービス識別子です。
Shared key (test): テストサービスのハッシュキーです。
保存済みの Shared key は、再度表示されることはありません。項目は空欄のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みのキーを削除するには、項目の下にある Clear the saved key on save にチェックを入れ、Save をクリックします。
Currencies: ご利用の Autopay サービスが受け付ける通貨です：PLN、EUR、GBP、USD、CZK。Autopay は通常、通貨ごとに個別のサービスを開設します。支払い方法は、チェックアウトの通貨がここで選択されている場合にのみ提供されます。既定値：PLN。
ITN と戻り先のアドレス
これらのアドレスを、本番用とテスト用の両方について、Autopay ポータルでご自身のサービスに入力してください。正確なアドレスは、このセクションの Addresses 項目に表示され、OpenCart インストールのストアアドレスから作成されます：
これらは OpenCart 3 のアドレスです。OpenCart 4 では次のとおりです：
アドレスは、設定に表示されているとおりに正確にコピーしてください。ITN URL がないと注文は確認されません。Autopay が支払いを確認するまで、OpenCart は注文をステータスなしのままにします。各 ITN は、通知で指定されたサービスの Shared key を使って作成された SHA-256 ハッシュで検証されます。有効なハッシュがない通知や、未知の Service ID を含む通知は拒否されます。通知は、その支払いが同じ Autopay サービスで開始された場合にのみ注文に適用されるため、テスト用の通知が本番の支払いを確認することはありません。Test mode を切り替える前に開始された支払いの通知は、両方の認証情報が保存されたままである限り、正しいキーを使って引き続き検証されます。
この拡張機能は ITN で次の支払いステータスを扱います：
Orders
OpenCart は、Confirm Order のステップで、ステータスのない注文（欠落注文）を作成します。注文がステータスを持つのは、Autopay が支払いを確認した（ITN SUCCESS）後だけです。支払いが失敗した場合や中断された場合、注文はステータスなしのままになります。OpenCart 4 では、支払いが完了していないチェックアウトの注文に Voided ステータスが設定されることがあります。これは、お客様が Confirm Order のステップに戻ったときに OpenCart 4 が設定するものです。拡張機能はこのような注文をステータスのない注文として扱い、後から届いた ITN SUCCESS により、その注文は引き続き支払い済みとしてマークされます。以下の各項目には、OpenCart の注文ステータスが一覧表示されます。
Order Status After Payment: Autopay が、想定どおりの金額と通貨で支払いを確認したときに設定されるステータスです。既定値：Processing。
On Hold Status: 支払われた金額または通貨が注文と異なる場合、または注文のステータスが変更された（例：キャンセルされた）後に支払いが届いた場合に設定されます。注文は支払い済みとしてマークされず、メモに理由が記載されます。既定値：Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。
Advanced
Logging: 支払いイベントを、OpenCart のログフォルダー（storage/logs）内の wc_ap_debug.log.php に書き込みます。このファイルはウェブから開くことができません。5 MB に達すると、wc_ap_debug.old.log.php に移動されます。キーとお客様のデータは、ログに記録されることはありません。既定値：オフ。オフの間は、エラーを含め何も書き込まれません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Import / Export
Export: Download JSON は、設定を JSON ファイルとして保存します。Shared key はエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの Shared key は保持されます。
チェックアウト
Payment Method のステップで、お客様が支払い方法を選択します（既定では Autopay）。Confirm Order のステップでは、お客様に説明文と You will be redirected to the secure Autopay payment page to complete the payment. という注記が表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。お客様が Confirm Order をクリックすると、ブラウザーが署名付きの支払いフォームを Autopay に送信します。このフォームには、注文通貨での注文合計、OrderID としての OpenCart 注文番号、番号付きの説明 Order、お客様のメールアドレスが含まれます。Autopay のページで、お客様は支払い方法を選択して支払いを行います。
注文が支払い済みとしてマークされるのは、Autopay が署名付きの ITN で確認し、金額と通貨が注文と一致した後だけです。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールと在庫の更新が行われます。支払い後、お客様はストアに戻ります。戻り先のアドレスは署名されていますが、注文を変更することはありません。注文にすでにステータスがある場合、お客様には OpenCart の注文完了ページが表示されます。ITN がまだ届いていない場合は、Payment confirmation のページに Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. と表示され、Check again と Back to checkout のボタンが表示されます。
Autopay が支払い失敗を報告した場合、お客様は The payment was not completed. You can try again or choose another payment method. というメッセージとともにチェックアウトに戻されます。カートは保持されます。新しい試行のたびに、新しい OpenCart 注文が作成されます（OpenCart 4 では、お客様は同じ OrderID のもとで新しい試行として、同じ注文に再度支払います）。同じカートの別の注文（同じ訪問での同じ商品）がすでに支払い済みの場合、お客様は再度支払うのではなく、成功ページに進みます。完了した購入の後に行う新しい購入は新しいカートとなり、通常どおり支払われます。支払いを開始できない場合、お客様は Confirm Order のステップに留まり、ボタンの上に短いメッセージが表示されます。たとえば Autopay payments are not configured. Please choose another payment method or contact the store. や、Autopay がこの通貨での支払いを受け付けられない旨です。
OpenCart 4 では、お客様は支払い方法ブロックの Choose ボタンを使い、Payment method options ウィンドウで支払い方法を選択して、チェックアウトページ下部の Confirm Order をクリックします。支払いが完了しなかったという内容のメッセージは、チェックアウトページの上部に表示されます。OpenCart 4 は、チェックアウトに対して 1 つの注文を保持し、その注文を更新します。その間にストアがその注文を閉じた場合（たとえば、管理者がキャンセルした場合）、お客様は The payment was not completed. You can try again or choose another payment method. というメッセージとともにチェックアウトに戻されます。注文が Autopay で支払い済みだった場合は、Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. というメッセージとともに戻されます。チェックアウトの注文が別のカートについてすでに支払い済みの場合、メッセージは Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. です。次の Confirm Order では新しい注文が支払われます。数量の変更を含め、カートに変更があった場合は新しいカートとみなされ、それ自体の支払いが必要になります。ITN はメンテナンスモードの間も機能します。OpenCart 4 では、このために拡張機能がスタートアップアクションを追加します。
この拡張機能には、OpenCart からの返金、サブスクリプションや定期払い、保存済みカード、チェックアウトページでの BLIK コードやカードフォーム、チェックアウトページでの銀行や支払いチャネルの選択はありません。また、環境ごとに 1 つの Service ID を使用します。
注文
Order statuses
No status (missing order): お客様は Autopay に送信されましたが、支払いを行っていないか、支払いが失敗したか、または Autopay がまだ支払いを確認していません。Sales > Orders では、Order Status フィルターを Missing Orders に設定した場合にのみ、このような注文が表示されます。
Order Status After Payment (default Processing): Autopay が支払いを確認し、金額と通貨が一致しました。メモには、金額、Autopay のトランザクション ID（remoteID）、支払日が表示されます。
On Hold Status (default Pending): Autopay が、注文合計と異なる金額または通貨を報告しました。注文は支払い済みとしてマークされません。Autopay ポータルでトランザクションを確認し、手動で完了させるか返金してください。この注文について後から正しい通知が届くと、支払い済みとしてマークされます。同じステータスは、ステータスを変更した（例：キャンセルした）後の注文に対して支払いが届いた場合にも使用されます。その場合、メモには、在庫を確認して注文を処理するか、支払いを返金するよう指示が表示されます。
支払い済みの注文が、後から届いた失敗の通知によって変更されることはありません。支払い済みの注文に対して Autopay が別の成功した支払いを報告した場合や、同じカートの 2 つ目の注文が支払われた場合、お客様が 2 回支払った可能性があるという警告メモが表示されます。別の Autopay サービスで開始された支払いの通知は適用されず、その旨がメモに表示されます。メモは、お客様には表示されない注文の History のエントリです。
VibeFox Autopay Payment tab
Sales > Orders で、Autopay で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Autopay Payment タブには、OrderID at Autopay、Service ID、テスト支払いの場合は Test mode ラベル付きの環境、Amount、Payment attempt のステータス、Autopay transaction ID、注文の Autopay notes が表示されます。このタブは読み取り専用で、拡張機能にアクセスできるユーザーに表示されます。
Refunds
Autopay を通じた返金はサポートされていません。Autopay ポータルで支払いを返金し、その後 OpenCart で注文を手動で更新してください。
ライセンスキー
この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox Autopay Payment のライセンスブロックは、Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit の最初のブロックで、設定の上に表示されます。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（たとえば、ライセンスの有効期限日とお使いのドメイン）が表示され、次のボタンも表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には、Product: opencart-payment-autopay の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックにその理由が表示されます。たとえば Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on などです。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認されたステータスのまま動作を続けます。
1 つのキーは 1 つのドメインで使用できます。これは、OpenCart の設定にあるストアアドレスを指します。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Autopay はチェックアウトでお客様に表示されません。それでも支払いが開始されてしまった場合、お客様には 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 ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
Autopay がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、選択した環境に Service ID と Shared key があること、そしてチェックアウトの通貨が Currencies で選択されていることを確認してください。これらのいずれかが欠けている場合、設定ページに警告が表示されます。支払い先住所が選択された Geo Zone 内にあること、注文が設定の Total に達していることも確認してください。
支払いは完了したが、注文がステータスなしのまま：Autopay が ITN を配信しなかったか、ストアがそれを拒否しました。設定に表示されている ITN URL が、Autopay ポータルでサービス（本番またはテスト）に設定されていること、ハッシュ関数が SHA-256 であること、そして拡張機能の Shared key がサービスと一致していることを確認してください。ストアがインターネットから到達可能であることも確認してください。Logging をオンにして、拡張機能ページの Log 項目を確認してください。
ログに ITN rejected: invalid hash と表示される：Shared key がサービスと一致しないか、サービスのハッシュ関数が SHA-256 ではありません。
ログに、service ID が設定されていないことが表示される：通知は、Service ID が拡張機能に入力されていないサービス、または Shared key が空のサービスから届きました。
ログに could not lock the order, Autopay will retry と表示される：注文が同時に別の通知によって処理されていました。ストアは、Autopay が通知を再送信するように応答します。
ブラウザーで ITN URL に METHOD_NOT_ALLOWED と表示される：これは正常です。この URL は Autopay からの POST リクエストのみを受け付けます。
注文が不一致のメモ付きで on-hold ステータスになっている：Autopay が、注文合計と異なる金額または通貨を報告しました。Autopay ポータルでトランザクションを確認し、注文を手動で完了させるか返金してください。
メモに、通知が適用されなかったと表示される：この注文の支払いは、この Autopay サービスで開始されていません。たとえば、本番の注文に対するテスト通知などです。Autopay ポータルでトランザクションを確認してください。
支払い後、お客様がホームページに戻される：戻り先のアドレスを検証できませんでした。たとえば、Service ID が拡張機能に入力されていないことが原因です。注文には影響しません。注文は ITN に従います。
お客様に This payment method is not available. Please reload the checkout page. と表示される：チェックアウトのセッションが注文と一致しなくなったか、支払い方法がその間にオフになったか、認証情報を失っています。お客様はチェックアウトを再読み込みします。
開発者向け：支払いフォームに署名する前に、拡張機能はフォームのパラメーターと注文を含む OpenCart イベント wc_ap_payment_params をトリガーします。このイベントでサービス、注文番号、金額、通貨を変更することはできません。
アンインストール
Extensions > Extensions に移動し、種類で Payments を選択して、VibeFox Autopay Payment の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能の独自の設定を削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。拡張機能は、Service ID や Shared key を含む他のゲートウェイ設定と、ログを常に削除します。設定を保持するオプションはありません。OpenCart 4 では、拡張機能のイベントと、メンテナンスモードでも ITN を通過させるスタートアップアクションも削除されます。Autopay の支払い記録は常に残ります。既存の注文は、支払いのメモを保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Autopay Payment の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱のボタン）をクリックして、アップロードしたパッケージを削除してください。
Autopay は、それぞれの所有者の商標です。この拡張機能は、Autopay と提携しておらず、Autopay による承認も受けていません。