VibeFox ePay.bg for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

通貨: ブルガリア・レフ（BGN）、ユーロ（EUR）、または米ドル（USD）。注文は、その注文の通貨で小数点以下 2 桁まで請求されます。顧客が別の通貨でチェックアウトした場合、支払い方法は表示されません。

ePay.bg アカウント: ePay.bg の加盟店プロフィールから、顧客番号（MIN）と秘密キーが必要です。本番用は www.epay.bg、テスト用は demo.epay.bg から取得します（テスト用アカウントは別途登録が必要です）。また、加盟店プロフィールにストアの通知 URL を入力する必要があります。

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

インストール

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

OpenCart 3

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

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

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

4. テスト用および/または本番用の MIN と秘密キーを入力します（設定を参照）。

5. Payment notifications (IPN) セクションに表示される URL を、ePay.bg の加盟店プロフィールの URL for receiving notifications フィールドにコピーします。デモと本番の両方のプロフィールで行ってください。これを行わないと、どの注文もステータスを受け取りません。

6. Enable/Disable をオンにして Save をクリックします。テストモードでテスト注文を行い、その後 Test Mode をオフにします。

OpenCart 4

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

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

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

4. ライセンスキーと ePay.bg の認証情報、および通知 URL を、OpenCart 3 のステップ 3 から 6 と同じように入力してください。設定ページとそのフィールドは両バージョンで同じです。異なるのは通知 URL だけです（支払い通知 (IPN) を参照）。

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

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体を保存します。設定の上部には、ストアの既定通貨が BGN、EUR、USD のいずれでもない場合にエラーが表示されます。支払い方法は有効なのに、選択中のモードの MIN または秘密キーが空の場合は警告が表示されます（その場合、チェックアウトでは非表示になり、保存時にも同じ警告が表示されます）。テストモードがオンの間は、Test mode is on: payments go to demo.epay.bg and no real money is charged. と表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は空にできず（最大 128 文字）、Sort Order は整数、Total は 0 以上の数値でなければなりません。いずれかのフィールドが正しくない場合は、何も保存されません。

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway で支払い方法のオン・オフを切り替えます。既定値: オフ。

Title: チェックアウトで顧客に表示される支払い方法の名前です。注文にも、この支払い方法名が保存されます。既定値: ePay.bg。必須。

Description: Confirm Order のステップで顧客に表示される説明文です。既定値: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Sort Order: チェックアウトの支払い方法の中での ePay.bg の表示順です。空欄のままにするか、整数を入力します。

Geo Zone: 選択した地域（ジオゾーン）の請求先住所に対してのみ ePay.bg を表示します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: ePay.bg を表示するために注文が達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも ePay.bg を表示します。

ePay.bg アカウント

顧客番号（MIN）と秘密キーは、www.epay.bg（本番）と demo.epay.bg（テスト用アカウント、別途登録）の加盟店プロフィールに表示されます。

Test Mode: テストモードを有効にします。顧客は ePay.bg のデモ環境に移動し、リクエストはテスト用の認証情報で署名されます。既定値: オン。オンの間は、Confirm Order のステップで顧客に Test mode (demo.epay.bg): no real payment is taken. と表示されます。

Test Merchant ID (MIN): demo.epay.bg の加盟店アカウントの顧客番号（MIN）です。

Test Secret Key: demo.epay.bg の加盟店アカウントの秘密キー（64 文字）です。

Live Merchant ID (MIN): www.epay.bg の加盟店アカウントの顧客番号（MIN）です。

Live Secret Key: www.epay.bg の加盟店アカウントの秘密キー（64 文字）です。HMAC-SHA1 署名に使用されます。

保存された秘密キーは再び表示されることはありません。フィールドは空欄になり、Saved — leave empty to keep it. と表示されます。値を変更する場合にのみ、新しい値を入力してください。保存済みの秘密キーを削除するには、フィールドの下にある Clear the saved key on save にチェックを入れ、Save をクリックします。貼り付けたキーに含まれる空白や改行は、保存時に削除されます。

支払い通知（IPN）

通知は、支払いリクエストが支払い済み、拒否された、または期限切れになったことをストアに伝えます。Notification URL フィールドには、ePay.bg の加盟店プロフィールで URL for receiving notifications として入力する URL が表示されます。本番とデモの両方のプロフィールで入力してください。URL は、OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify、OpenCart 4 では https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify のような形式で、OpenCart インストールのストアフロントのアドレスから生成されます。設定に表示されたとおりに、URL を正確にコピーしてください。注文がステータスを受け取るのは、この署名付き通知によってのみです。顧客がストアに戻っても、注文は支払い済みになりません。

ePay.bg は、各請求書について次の結果を報告します。

有効なチェックサムのない通知は拒否され、ePay.bg は通知を送信し続けます。チェックサムは、キーを持つ各モードの秘密キーで検証されるため、テストと本番を切り替える前に開始された支払いも引き続き確認されます。支払いは、そのリクエストが行われたモードで届く必要があります。そうでない場合、注文は on-hold 状態になります。加盟店プロフィールに通知 URL が設定されていない場合、どの注文もステータスを受け取りません。

支払いリクエスト

Invoice Prefix: 数字のみ（最大 10 桁）。OpenCart の注文 ID の前に付けて ePay.bg の請求書番号を作成します（例: 00001 + 123 = 00001123）。同じ ePay.bg アカウントで複数のストアを使用する場合は、ストアごとに異なる接頭辞を使用してください。それ以外の文字は保存時に削除され、保存された接頭辞を示す警告が表示されます。後から接頭辞を変更しても問題ありません。未処理の支払いリクエストは、それぞれに保存された請求書番号によって見つけられます。既定値: 00001。

Expiration Time: 未払いの支払いリクエストの有効期限です。期限を過ぎると、ePay.bg は期限切れとして報告し、注文はステータスを受け取りません。1、3、6、12、24、48、72 時間から選択します。時刻はストアのタイムゾーンに関係なく、ブルガリア時間で送信されます。既定値: 24 時間。

Language: ePay.bg の支払いページの言語です。英語またはブルガリア語。既定値: English。

注文

OpenCart は Confirm Order のステップで、ステータスなし（欠落注文）として注文を作成します。注文がステータスを受け取るのは、ePay.bg が支払いを報告した後だけです。拒否、期限切れ、または中断された支払いでは、注文はステータスなしのままになり、顧客は再度支払うことができます。以下のステータスフィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 支払いが成功した後に設定されるステータスです。

Processing status: Default と Processing に対応する OpenCart のステータスです。既定値: Processing。

Completed status: Completed に対応する OpenCart のステータスです。既定値: Complete。

On Hold status: On Hold と、手動確認が必要な支払いに対応する OpenCart のステータスです。支払いリクエストの後に注文の合計金額または通貨が変更された場合、通知が別のモードで届いた場合、または支払いが届く前に注文ステータスが変更された場合（例: キャンセル）に使用されます。このような注文は支払い済みとしてマークされず、理由はメモに記載されます。既定値: Pending。OpenCart には On hold のステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

詳細設定

Logging: 支払いリクエストと通知を、OpenCart のログフォルダ（storage/logs）内の epay_bp_debug.log.php に書き込みます。このファイルはウェブから開くことはできず、5 MB に達すると epay_bp_debug.old.log.php に移動されます。秘密キーやカードデータは記録されません。既定値: オフ。オフの間もエラーは常に記録されます。

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

Delete Data on Uninstall: オンにすると、拡張機能をアンインストールしたときに、ゲートウェイの設定とログが削除されます。ePay.bg の支払い記録と注文は常に保持されます。既定値: オフ。

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

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

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

チェックアウト

Payment Method のステップで、顧客は支払い方法を選択します（既定では ePay.bg）。Confirm Order のステップでは、顧客に説明文と、You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. というメモが表示されます。OpenCart は、このステップで注文を作成しますが、まだステータスは設定されていません。OpenCart 4 では、支払い方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで支払い方法を選んでから、チェックアウトページ下部の Confirm Order をクリックします。顧客が Confirm Order をクリックすると、拡張機能は、注文通貨での注文合計金額について、請求書番号と有効期限を含む署名付きの支払いリクエストを送信し、顧客を ePay.bg に移動させます。ePay.bg 上では、支払いは Order と注文番号として表示されます。ePay.bg では、顧客は銀行カードまたは ePay.bg アカウントで支払います。

支払い後、顧客はストアに戻ります。注文が支払い済みとしてマークされるのは、ePay.bg が署名付きの通知によって確認した後だけです。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールが送信され、在庫が更新されます。通知がすでに届いている場合、顧客には OpenCart の注文完了ページが表示されます。届いていない場合、Payment confirmation のページに Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. と表示され、Check again および Back to checkout のボタンが表示されます。

顧客が ePay.bg でキャンセルした場合、チェックアウトに戻り、The ePay.bg payment was cancelled. You can try again or choose another payment method. と表示されます。ePay.bg がリクエストを拒否または期限切れとして報告した場合、メッセージは The payment was not completed. You can try again or choose another payment method. です。カートは保持されます。OpenCart 4 では、これらのメッセージはチェックアウトページの上に表示されます。同じ注文に対する新しい試行では、同じ請求書番号が使用されます。OpenCart 3 は Confirm Order のステップが表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を 1 つ保持して更新するため、新しい試行は新しい支払いリクエストで同じ注文を支払います。同じカートの別の注文がすでに支払い済みである場合、顧客は完了ページに移動し、新たな支払いは開始されません。

OpenCart 4 は、成功ページが表示されるまで注文をチェックアウトに保持します。その間に注文が支払いなしで閉じられた場合（たとえばキャンセルした場合）、顧客は Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. と表示されてチェックアウトに戻り、次の Confirm Order でそのカートの新しい注文の支払いが行われます。注文がすでに支払い済みでも、その後カートが変更されている場合（数量の変更を含む）、顧客はチェックアウトに戻り、次の Confirm Order で新しいカートを新しい注文で支払います。支払い済みの注文が、別のカートに対して支払い済みとして表示されることはありません。

注文を ePay.bg で支払えない場合、顧客は Confirm Order のステップにとどまり、ボタンの上に短いメッセージが表示されます。例えば ePay.bg payments are temporarily unavailable. Please choose another payment method.、または ePay.bg が注文通貨での支払いを受け付けていないことを示すメッセージです。

OpenCart 3 では支払い拡張機能のリクエストが通過し、OpenCart 4 では拡張機能が通知のためのスタートアップアクションを追加するため、ストアがメンテナンスモードであっても通知は機能します。すでに開始された支払いの通知は、支払い方法をオフにした場合でも受け付けられます。

この拡張機能は、ePay.bg での 1 回限りの支払いのみに対応しています。OpenCart からの返金、保存済みカード、サブスクリプションや定期払い、EasyPay や B-Pay の現金支払いコードには対応していません。

注文

注文ステータス

No status (missing order): 顧客は ePay.bg に移動しましたが支払っていない、通知がまだ届いていない、または ePay.bg がリクエストを拒否または期限切れとして報告した状態です。Sales > Orders では、Order Status フィルターを Missing Orders に設定した場合にのみ、このような注文が表示されます。

Processing, Completed または On Hold status: 支払いが確認された状態です。ステータスは Order Status After Payment に従います。メモには、請求書番号、支払い日、STAN、BORICA コードが表示されます。

支払い後の On Hold status: 支払いは届きましたが、注文の現在の内容とは一致していません。支払いリクエストの後に注文の合計金額または通貨が変更された、通知がリクエストとは別のモード（テストまたは本番）で届いた、または注文の支払い方法がもはや ePay.bg ではない、といった場合です。この支払いは支払い済みとして記録されません。すでに注文に別のステータス（例: キャンセル）を設定していた場合も同様です。理由はメモに記載されます。ePay.bg の加盟店パネルで支払いを確認し、注文を手動で処理するか、返金してください。

すでに支払い済みの注文に対して支払いが届いた場合、ステータスは変更されず、メモで ePay.bg の加盟店パネルにおける二重払いを確認するよう指示されます。顧客が同じカートの 2 つの注文を支払った場合、2 つ目の注文には二重払いの可能性を示すメモが付きます。支払い拒否や期限切れの遅延通知によって、支払い済みの注文が変更されることはありません。すでにステータスがある注文にはメモのみが追加されます。

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

VibeFox ePay.bg Gateway タブ

Sales > Orders で、ePay.bg で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox ePay.bg Gateway タブには、請求書、環境（テストまたは本番。テストの支払いには Test mode のラベルが付きます）、リクエストされた金額と通貨、支払いリクエストの状態、通知結果、支払い日、STAN、BORICA コード、注文の ePay.bg notes が表示されます。このタブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

ePay.bg の WEB API には返金のためのリクエストがないため、OpenCart からの返金は利用できません。ePay.bg の加盟店パネルで支払いを返金してから、OpenCart で注文ステータスを手動で更新してください。Sales > Returns での商品返品では、ePay.bg を通じて返金は行われません。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox ePay.bg Gateway は、Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit の最初のブロックで、設定の上部にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（たとえばライセンスの有効期限日とドメイン）、そして次のボタンが表示されます。Check now はステータスを再確認します。Change key は別のキーを入力します。Remove key は、このストアからキーを削除します。その下には Product: opencart-payment-epaybg という行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、ePay.bg はチェックアウトで顧客に表示されません。それでも支払いが開始された場合、顧客には 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 週間に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは必ず削除されます。

トラブルシューティング

ePay.bg がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択したモードの MIN と秘密キーが設定されていること、そして顧客が BGN、EUR、USD のいずれかでチェックアウトしていることを確認してください。認証情報が不足している場合、設定ページに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文にステータスが設定されない: 注文は ePay.bg の通知からのみステータスを受け取ります。使用しているモード（デモまたは本番）の ePay.bg 加盟店プロフィールに、Notification URL に表示されたとおりの通知 URL が正確に入力されているか、そのモードの秘密キーが正しいかを確認してください。拡張機能のページにある Log フィールドを確認し、Logging をオンにすると、すべての通知を確認できます。

通知が ERR=Not valid CHECKSUM で応答する: 通知を送信した加盟店プロフィールと一致する、保存済みの秘密キーがありません。ePay.bg は再試行を続けるため、キーが正しくなった時点で注文はステータスを受け取ります。

通知が ERR=Not configured で応答する: 秘密キーが保存されていません。入力してください。

通知が請求書に対して STATUS=NO で応答する: その請求書はこのストアで発行されたものではありません。たとえば、同じ ePay.bg アカウントを使用している別のストアが発行したものです。ストアごとに異なる Invoice Prefix を設定してください。

通知が STATUS=ERR で応答する: 一時的なエラーです。たとえば、同じタイミングで同じ注文に対して 2 つの通知が届いた場合、または注文のステータスを設定できなかった場合です。ePay.bg は通知を再送します。理由はログに記録されています。

通知 URL に ERR=Method not allowed in the browser と表示される: これは正常です。この URL は ePay.bg からのリクエストのみを受け付けます。

顧客に This payment method is not available. Please reload the checkout page. と表示される: チェックアウトのセッションが注文と一致しなくなったか、その間に支払い方法がオフにされました。顧客はチェックアウトを再読み込みします。

顧客に This order has nothing to pay. と表示される: 注文の合計金額がゼロのため、ePay.bg に送信するものがありません。

注文が支払い後に On Hold status になっている: VibeFox ePay.bg Gateway タブのメモを確認し（注文ステータスを参照）、ePay.bg の加盟店パネルで支払いを確認してから、注文を処理するか、そこで返金してください。

保存時に請求書の接頭辞が変更された: 接頭辞には数字のみを使用でき、最大 10 桁です。それ以外の文字は削除されます。

開発者向け: 支払いフォームが ePay.bg に送信される前に、拡張機能はフォームのフィールドと注文を伴う OpenCart イベント epay_bp_form_fields をトリガーします。これは、たとえば直接カード支払いページ（PAGE=credit_paydirect）を使用するためです。このイベントによって、署名されたデータとチェックサムを変更することはできません。

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox ePay.bg Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。具体的には Enable/Disable、Sort Order、Geo Zone、Total、そして Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。OpenCart 4 では、拡張機能のイベントと、メンテナンスモードで通知を通過させるスタートアップアクションも削除されます。Delete Data on Uninstall がオンの場合は、その他のゲートウェイ設定（タイトル、説明、テストモード、MIN と秘密キー、支払いリクエスト、支払い後の注文ステータス、ログ）とログも削除されます。オフの場合は、後で再インストールする際のために保持されます。ePay.bg の支払い記録は常に保持されるため、再インストールの前に開始された支払いも引き続き確認されます。既存の注文は、支払いのメモを保持します。

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

ePay.bg は、それぞれの所有者の商標です。この拡張機能は ePay.bg と提携しておらず、ePay.bg による承認もありません。