VibeFox ifthenpay for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。
PHP: 8.0 以降。
通貨: ユーロ（EUR）のみ。EUR 通貨がストアで有効になっている必要があり、決済方法は購入者が EUR で支払う場合にのみ表示されます。ifthenpay は 0.01 から 99,999.99 EUR までの合計金額を受け付けます。
ifthenpay アカウント: ifthenpay.com でサインアップしてください。提供する決済方法のキーが必要です: Multibanco、MB WAY、Credit Card（形式は ABC-123456）。キーは ifthenpay のバックオフィス（backoffice.ifthenpay.com）に表示されるか、アカウントでその決済方法が有効化されたときに ifthenpay から送られます。ifthenpay がお使いのキーのコールバックを有効にする必要もあり（設定を参照）、ストアがインターネットから到達可能である必要があります。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ wcp_ifthenpay_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_ifthenpay_gateway.ocmod.zip です。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer を開き、Upload をクリックして wcp_ifthenpay_gateway-oc3-(version).ocmod.zip ファイルを選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージ内の upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox ifthenpay Gateway を見つけ、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、決済拡張機能の一覧を変更する権限が必要です。拡張機能はインストール時に anti-phishing キーを生成します。
3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. Payment Method を選択し、その ifthenpay キーを入力して Save をクリックします。これにより Callback URL が選択した決済方法と一致します。
5. Callback セクションから Anti-phishing Key と Callback URL をコピーし、キーのコールバックを有効にするよう ifthenpay に依頼します（バックオフィスまたは ifthenpay サポート経由）。
6. Enable/Disable をオンにして Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer を開き、Upload をクリックして wcp_ifthenpay_gateway.ocmod.zip ファイルを選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox ifthenpay Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。
4. ライセンスキー、決済方法とそのキーを入力し、OpenCart 3 の手順 3 から 6 と同様にコールバックを有効にします。設定ページとそのフィールドは両方のバージョンで同じです。違うのはコールバック URL だけです（Callback を参照）。
新規インストール時は、決済方法がオフ、テストモードがオフの状態になります。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit。セクションは左側に並んでおり、一覧の下にある Save ボタンでページ全体を保存します。選択した決済方法のキーがない場合、チェックアウトに決済方法は表示されません。そのキーがないままゲートウェイが有効になっている間、ページには ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. と表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。
保存時には、決済方法が有効であること、タイトルは 128 文字以内であること、Sort Order は整数であること、Total は 0 以上の数値であること、そしてジオゾーンと注文ステータスが存在することが必要です。これらを満たさない場合は、何も保存されません。
ifthenpay
Enable/Disable: Enable ifthenpay Payment で決済方法をオンまたはオフにします。既定値: オフ。
Title: チェックアウトで表示される決済方法のタイトルです。注文に保存される決済方法の名前にもなります。既定値: ifthenpay。空欄にすると、チェックアウトには ifthenpay と表示されます。
Description: Confirm Order ステップで、確認ボタンの上に購入者に表示されるテキストです。既定値: Pay via Multibanco, MB WAY or Credit Card. 提供する決済方法に合わせて変更してください。
Payment Method: チェックアウトで提供される決済方法です。その方法のキーのみ必須です。
Sort Order: チェックアウトにおける決済方法の中での ifthenpay の表示順です。空欄のままにするか、整数を入力します。
Geo Zone: 選択したジオゾーン内の請求先住所に対してのみ ifthenpay を提供します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。
Total: ifthenpay が提供されるために注文が達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの合計金額でも ifthenpay が提供されます。ifthenpay 自体は、購入者が EUR で支払い、かつ金額が 0.01 から 99,999.99 EUR の場合にのみ提供されます。
ifthenpay のキー
キー（形式は ABC-123456）は、ifthenpay のバックオフィス（このセクションからリンクされています）に表示されるか、アカウントでその決済方法が有効化されたときに ifthenpay から送られます。
Multibanco Key: 動的な参照番号（dynamic references）用の ifthenpay Multibanco（MB）キーです。
MB WAY Key: ifthenpay MB WAY キーです。
Credit Card Key: ifthenpay Credit Card キーです。また、カードページからの購入者の戻りの署名を検証します。
保存済みのキーは再表示されません。欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みのキーを削除するには、欄の下にある Clear the saved key on save にチェックを入れて Save をクリックします。
Callback
コールバックは、決済が行われたことをストアに通知します。使用する各キーについて、このセクションの Anti-phishing Key とコールバック URL を添えて、コールバックを有効にするよう ifthenpay に依頼してください。Multibanco と MB WAY の注文はコールバックによってのみ確認されます。カード決済は、カードページからの署名付きの戻りによっても確認されます。
Anti-phishing Key: 拡張機能によって生成され、コピー用に表示されます。ifthenpay はすべてのコールバックでこのキーを返送します。キーのないコールバックは拒否されます。
Callback URL: 選択した決済方法のコールバック URL で、ifthenpay のプレースホルダーを含み、コピー用に表示されます。URL は OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback、OpenCart 4 では https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback で始まり、OpenCart インストールのストアフロントのアドレスから作られ、決済方法のパラメーターが続きます。URL は設定画面に表示されたとおりに、全体を正確にコピーしてください。Payment Method を変更した場合は、保存してから新しい URL をコピーしてください。
各コールバックの anti-phishing キーは、お使いのキーと照合されます。キーがないか誤っている場合は 403 が返され、注文は変更されません。コールバックは、この拡張機能の決済とも一致している必要があります。Multibanco の場合はエンティティと参照番号、MB WAY の場合は注文とその MB WAY リクエストの 1 つ、Credit Card の場合は注文とそのカードリクエストの 1 つです。正しく動作するコールバックがなければ、Multibanco と MB WAY の注文は確認されず、カード決済は署名付きの戻りによってのみ確認されます。コールバックは、ストアがメンテナンスモードの間も機能します。OpenCart 3 は決済拡張機能のリクエストを通過させ、OpenCart 4 では、拡張機能がコールバックと、カードページからの購入者の戻りを通過させる起動アクションを追加します。
Orders
OpenCart は Confirm Order ステップで、ステータスなし（注文の欠落）の注文を作成します。Multibanco と MB WAY では、ifthenpay が参照番号または MB WAY リクエストを発行すると、注文は待機ステータスになります。Credit Card では、コールバックまたは署名付きの戻りがあって初めて注文にステータスが付与されます。注文が支払い済みとしてマークされるのは、金額が注文合計と 1 セント単位まで一致する場合だけです。以下の各欄では、お使いの OpenCart 注文ステータスを選択できます。
Order Status After Payment: 決済が確認されたときに設定されるステータスです。既定値: 処理中。
Awaiting payment status: Multibanco の参照番号または MB WAY リクエストが発行され、購入者はまだ支払う必要があります。Multibanco の詳細は、このステータスとともに注文メールと購入者の注文履歴で送られます。既定値: 保留中。
Payment on hold status: ifthenpay が、注文と一致しない決済（金額、通貨）、注文のキャンセル後の決済、またはカートが既に支払い済みの注文の決済を報告しました。メモに理由が記載されます。既定値: 保留中。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。
詳細設定
Test Mode: Credit Card と Multibanco は ifthenpay のサンドボックスエンドポイントを使用します。実際の料金は請求されず、ifthenpay が提供するテストキーを使用します。MB WAY にはサンドボックスがないため、ifthenpay のテストキーでテストしてください。Confirm Order ステップには TEST MODE バッジが表示されます。既定値: オフ。
Debug Log: API リクエストとコールバックは、OpenCart のログフォルダ（storage/logs）にある ifthenpay_p_debug.log.php に書き込まれます。このファイルはウェブから開くことはできず、5 MB でローテーションされます。エラーは常に記録されます。キー、anti-phishing キー、電話番号の全文は記録されません。既定値: オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログを空にできます。
Delete Data on Uninstall: オンにすると、拡張機能をアンインストールしたときにゲートウェイの設定、anti-phishing キー、ログが削除されます。注文と ifthenpay の決済記録は常に保持されます。既定値: オフ。
インポート / エクスポート
Export: Download JSON を使うと、設定を JSON ファイルとして保存します。ifthenpay のキーはエクスポートされません。
Import: 以前エクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します。保存済みのキーは保持されます。
チェックアウト
Payment Method ステップで、購入者は決済方法を選択します（既定では ifthenpay）。Confirm Order ステップでは、購入者に貴店の説明と決済方法のヒントが表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。
OpenCart 4 では、購入者は決済方法ブロックの Choose ボタンで、Payment method options ウィンドウから決済方法を選び、チェックアウトページ下部の Confirm Order をクリックします。
Multibanco。購入者には You will receive a Multibanco reference to complete the payment. と表示されます。購入者が Confirm Order をクリックすると、拡張機能は注文合計に対する動的な Multibanco 参照番号を作成し、注文は Awaiting payment status になります。注文の完了ページには Multibanco Payment Details が表示されます。エンティティ、参照番号、金額で、Please use these details to pay at any Multibanco ATM or through your online banking. が続きます。同じ詳細は注文メールでも送られ、購入者の注文履歴に表示されます。同じ金額で既に注文に対して参照番号が発行されている場合は、それが再利用されます。ifthenpay が決済コールバックを送ると、注文は支払い済みになります。
MB WAY。購入者は MB WAY phone number（912 345 678、+351 912 345 678、または他国向けの 351#912345678）を入力します。注文の電話番号が入力されています。拡張機能は電話に決済リクエストを送信し、注文は Awaiting payment status になります。注文の完了ページには A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. と表示されます。ifthenpay がコールバックを送ると、注文は支払い済みになります。保存されるのはマスクされた電話番号だけです。既定では OpenCart 4 はチェックアウトで電話番号を尋ねません。その欄は空欄になり、購入者が番号を入力します。
Credit Card。購入者には You will be redirected to a secure page to enter your card details. と表示され、ifthenpay のカードページに移動します。注文はステータスなしのままで、カートは保持されます。決済が成功すると、購入者は貴店に戻ります。戻りは、有効な ifthenpay の署名、その試行の秘密値、および注文のカードリクエストがある場合にのみ受け付けられます。その場合、注文は支払い済みとしてマークされ、購入者は OpenCart の注文完了ページを表示します。戻りを検証できない場合は何も変更されず、Payment confirmation ページに Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. が、Check again と Back to checkout のボタンとともに表示されます。コールバックが届き次第、決済は確認されます。カード決済が失敗または取り消された場合、購入者は The card payment was not completed. You can try again or choose another payment method. または The card payment was cancelled. You can try again or choose another payment method. とともにチェックアウトに戻ります。注文のカード試行はすべて保持されるため、古いタブで行われた決済も受け付けられます。OpenCart 4 では、これらのメッセージはチェックアウトページの上に表示されます。
決済が確認されると、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールが送られます。OpenCart 3 は、Confirm Order ステップが表示されるたびに新しい注文を作成します。OpenCart 4 では注文がチェックアウトで更新されるため、カード決済がキャンセルまたは失敗した後、または MB WAY リクエストが拒否された後、購入者は新たな試行で同じ注文を支払います。同じカートに既に支払い済みの注文、または Multibanco か MB WAY の支払いを待っている注文がある場合、購入者は新たに決済を開始するのではなく、その注文の完了ページに移動します。Multibanco の詳細と MB WAY のヒントは、注文が支払い待ちの間だけ完了ページに表示されます。カートに変更（新しい数量を含む）があった場合は、別途支払いが必要な新しいカートとして扱われます。
OpenCart 4 では、注文は完了ページが表示されるまでチェックアウトに保持されます。その注文が途中で決済なしに閉じられた場合（たとえば、Multibanco の支払いを待っていた注文をキャンセルした場合）、購入者は Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. とともにチェックアウトに戻されます。注文が既に確定していて、その後カートが変更された場合のメッセージは Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. です。どちらの場合も、次の Confirm Order でカートの新しい注文が支払われます。
決済を開始できない場合、購入者はボタンの上に短いメッセージが表示された状態で Confirm Order ステップに留まります。たとえば The Multibanco reference could not be created. Please try again or choose another payment method.、The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method.、または The payment service is temporarily unavailable. Please try again in a few minutes. です。技術的な理由はログに書き込まれます。
この拡張機能は、一度に 1 つの ifthenpay 決済方法を提供します。Payshop、Cofidis Pay、Apple Pay、Google Pay、PIX、Pay-by-Link には対応しておらず、サブスクリプションや保存済みカードもありません。未払いの Multibanco 参照番号の自動期限切れやキャンセルも、決済状況のポーリングもありません。
注文
注文ステータス
No status (missing order): カード決済は開始されたものの、まだ確認されていないか、失敗またはキャンセルされました。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定したときにのみ表示されます。
Awaiting payment status (default Pending): Multibanco の参照番号が発行されたか、MB WAY リクエストが送信されました。未払いの参照番号や拒否された MB WAY リクエストは、注文を自動的にキャンセルしません。必要であれば、そのような注文はご自身でキャンセルしてください。
Order Status After Payment (default Processing): 決済が確認されました。メモには、Multibanco の参照番号、MB WAY のトランザクション、またはカードリクエスト ID、および確認方法が表示されます。
Payment on hold status (default Pending): 受け取った金額が注文合計と異なる（たとえば、カード決済の開始後にカートが変更された）、注文のキャンセル後に決済が届いた、または同じカートの別の注文が既に支払い済みだった場合です。メモにその理由が記載され、購入者に再度支払いを求めることはありません。ifthenpay のバックオフィスで決済を確認し、注文を手動で完了させるか返金してください。このような注文に後から正しい決済が届いても、注文は変更されません。
既に支払い済みの注文に対する 2 回目の決済は、重複した決済がないかを ifthenpay のバックオフィスで確認するよう促すメモを追加するだけです。（返金済みなど）別のステータスに変更した注文が再オープンされることはありません。その場合はメモが追加されます。
メモは、購入者には表示されない注文の History の項目です。
VibeFox ifthenpay Gateway タブ
Sales > Orders で、ifthenpay で支払われた注文を開きます。注文ページの下部、History と Additional の隣に、VibeFox ifthenpay Gateway タブが表示されます。このタブには、注文の決済試行の一覧（日付、方法、テスト決済の場合は Sandbox ラベル、金額、Multibanco のエンティティと参照番号、またはマスクされた MB WAY の電話番号、ifthenpay のリクエスト ID とステータス）、注文が保留中である間の Payment on hold 警告、そして注文の ifthenpay notes が表示されます。このタブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。
返金
OpenCart からの返金はサポートされていません。ifthenpay のバックオフィスで決済を返金し、OpenCart には手動で記録してください。Sales > Returns での商品返品では、ifthenpay を通じて返金は行われません。返金済み（DEVOLVIDO）のコールバックは、メモを追加するだけです。ifthenpay が報告するその他のステータスも、メモを追加するだけです。
ライセンスキー
この拡張機能は、vibefox.net から取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox ifthenpay Gateway は、Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、このブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスが有効な期限日やドメインなど）と、ボタンが表示されます。ボタンは、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）です。その下には、Product: opencart-payment-ifthenpay という行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで購入者に ifthenpay は表示されません。それでも決済が開始された場合、購入者には 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 ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに ifthenpay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択した Payment Method のキーが入力されていること、購入者が EUR で支払うこと、そして合計金額が 0.01 から 99,999.99 EUR の間であることを確認してください。また、支払い先住所が選択した Geo Zone に含まれていること、および注文が設定の Total に達していることも確認してください。
購入者は支払ったが、注文が待機ステータスまたはステータスなしのまま: コールバックがストアに届いていません。ifthenpay が、使用しているキーについてコールバック URL と anti-phishing キーを有効にしていること、そして URL が選択した決済方法のものであることを確認してください。ストアはインターネットから到達可能である必要があり、localhost やログインの背後にあってはいけません。Debug Log をオンにして、拡張機能のページにある Log 欄を確認してください。
コールバックの応答が 403 Forbidden: コールバック内の anti-phishing キーがないか、設定のキーと異なります。設定に表示されているキーを ifthenpay に再送信してください。
コールバックの応答が 503 Not configured: anti-phishing キーがまだ生成されていません。拡張機能の設定を一度開いてください。ifthenpay はコールバックを再試行します。
コールバックの応答が 503 Busy: 同じ注文がその時点で別のリクエストによって処理されていました。ifthenpay はコールバックを再試行します。
コールバックの応答が Order not found: 参照番号またはリクエストがこの拡張機能の決済に属していないか、注文が別の決済方法で行われました。
支払い済みの注文が保留になったのはなぜですか？ 受け取った金額が注文合計と異なった、注文のキャンセル後に決済が届いた、または同じカートの別の注文が既に支払い済みだった、といった理由です。VibeFox ifthenpay Gateway タブのメモを確認し、ifthenpay のバックオフィスで決済を確認してから、注文を手動で完了させるか返金してください。
MB WAY リクエストを送信できませんでした: 電話番号が MB WAY に登録されていないか、形式が誤っています。912 345 678 を使用するか、他国の番号の場合は 351#912345678 を使用してください。
テストモードと MB WAY: ifthenpay には MB WAY のサンドボックスがありません。ifthenpay が提供するテストキーを使用してください。
アンインストール
Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox ifthenpay Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。具体的には、Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントと、メンテナンスモードでコールバックと購入者の戻りを通過させる起動アクションも削除されます）。Delete Data on Uninstall がオンの場合、その他のゲートウェイ設定、anti-phishing キー、ログが削除されます。再インストール後は新しい anti-phishing キーが生成され、それを ifthenpay に再度送信する必要があります。オフの場合は、後で再インストールするために保持されます。ifthenpay の決済記録（参照番号とリクエスト ID）は常に保持されるため、以前に発行された参照番号へのコールバックは、再インストール後もその注文を見つけられます。既存の注文は、決済のメモを保持します。
OpenCart 4 で拡張機能のファイルも削除する場合は、アンインストール後に Extensions > Installer を開き、インストール済み拡張機能の一覧で VibeFox ifthenpay Gateway の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次に Delete（赤いゴミ箱ボタン）をクリックして、アップロードされたパッケージを削除してください。
ifthenpay は、それぞれの所有者の商標です。この拡張機能は ifthenpay と提携しておらず、ifthenpay による推奨も受けていません。