VibeFox ePay.bg for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。

通貨: ブルガリア・レフ（BGN）、ユーロ（EUR）、米ドル（USD）。カートは自身の通貨で、小数点以下 2 桁まで請求されます。その他の通貨のカートでは、チェックアウト時に支払い方法が表示されません。

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

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

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox ePay.bg Gateway を探し、Configure をクリックすることもできます。

3. Configure ページ上部のライセンスブロックで、VibeFox ライセンスキーを License key に入力し、Activate をクリックします（ライセンスキーの項を参照）。

4. テストおよび/または本番の MIN とシークレットキーを入力します（「設定」を参照）。

5. Payment notifications (IPN) セクションに表示される URL を、URL for receiving notifications フィールドに貼り付けます。場所は ePay.bg の加盟店プロフィール（デモと本番の両方）です。これを行わないと注文は作成されません。

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

インストール時にモジュールは注文ステータス ePay.bg payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox ePay.bg Gateway > Configure。各 Save ボタンはページ全体を保存します。フィールドの上には、ストアの既定通貨が BGN、EUR、USD のいずれでもない場合はエラーが、ゲートウェイが有効なのに選択したモードの MIN またはシークレットキーが空の場合は警告が表示されます（その場合は、チェックアウトで非表示になり、保存時にも同じ警告が表示されます）。さらにテストモードが有効な間は Test mode is on: payments go to demo.epay.bg and no real money is charged. が表示されます。

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway は支払い方法を有効または無効にします。既定値：オフ。

Title: チェックアウトで購入者に表示される支払い方法の名前です。注文に保存される支払い方法名でもあります。既定値：ePay.bg。必須。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay securely via ePay.bg with a bank card or your ePay.bg account.

ePay.bg アカウント

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

Test Mode: テストモードを有効にします。購入者は ePay.bg のデモ環境に移動し、リクエストはテスト用の認証情報で署名されます。既定値：オン。

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 saved secret keys: キーにチェックを入れて Save をクリックすると削除されます。空のフィールドは保存済みの値を保持します。

Payment notifications (IPN)

通知は、支払いリクエストが支払い済み、拒否された、または期限切れになったことをストアに伝えます。Notification URL フィールドには、ePay.bg の加盟店プロフィールで URL for receiving notifications として入力する URL が表示されます（本番とテストの両方）。わかりやすい URL を使用している場合は、https://your-shop/module/wcp_epaybg_gateway/notify のような形式になり、/en/ のような言語コードが付くこともあります。設定に表示されたとおりに URL をコピーしてください。注文は、この署名付き通知によってのみ作成されます。購入者がストアに戻っても、注文が作成されたり支払われたりすることはありません。

ePay.bg は、請求書ごとに次の結果を報告します：

PAID: 購入者が支払いました。注文が作成されます。

DENIED: 支払いが拒否されました。注文は作成されません。

EXPIRED: 支払いリクエストが未払いのまま期限切れになりました。注文は作成されません。

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

Payment request

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

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

Language: ePay.bg の決済ページの言語（英語またはブルガリア語）です。既定値：英語。

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

Default (Payment accepted): 支払い済み注文に対する PrestaShop の標準ステータス（既定）。

Processing (Payment accepted): 同じステータス、「支払い受付」。

Completed (Delivered): 支払い済みのすべての注文が「配送済み」になります。

On Hold: 支払い済みのすべての注文は、手動で確認するために ePay.bg payment on hold になります。支払い内容は引き続き注文に記録されます。

Advanced

Logging: 支払いリクエストと通知を、モジュールフォルダー内の logs/epay_bp_debug.log.php に書き込みます。このファイルは Web から開くことはできません。シークレットキーとカード情報は記録されません。既定値：オフ。オフの間もエラーは常に記録されます。

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

Delete Data on Uninstall: オンの場合、モジュールをアンインストールするとゲートウェイ設定とログが削除されます。ePay.bg の支払い記録、注文ステータス ePay.bg payment on hold、および注文は常に保持されます。既定値：オフ。

チェックアウト

支払いステップで、購入者は支払い方法（既定では ePay.bg）を選び、確定します。購入者には Redirecting to ePay.bg for payment... と表示され、カート通貨でのカート合計、請求書番号、有効期限を含む署名付き支払いリクエストとともに ePay.bg に移動します。ePay.bg 上では、支払いは Cart とカート番号として表示されます。ページには、リダイレクトが開始されなかった場合のための Pay via ePay.bg ボタンと、Cancel ボタンもあります。ePay.bg 上で、購入者は銀行カードまたは ePay.bg アカウントで支払います。この時点ではまだ注文は存在しません。

支払い後、購入者は貴店に戻ります。注文は、署名付きの ePay.bg 通知が届いたときにのみ作成されます。すでに届いている場合、購入者には標準の注文確認ページが表示されます。まだの場合は、Payment confirmation ページに Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. と表示され、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. です。カートは保持されます。同じカートで再試行すると、同じ請求書番号が使用されます。

カートを ePay.bg で支払えない場合、購入者は短いメッセージ（例：ePay.bg payments are temporarily unavailable. Please choose another payment method.、またはカート通貨では ePay.bg が支払いを受け付けないという内容）とともにチェックアウトに残ります。

通知はストアがメンテナンスモードの間も機能し、ストアの国別制限でブロックされることもありません。

モジュールが受け付けるのは、ePay.bg での 1 回限りの支払いのみです。PrestaShop からの返金、保存済みカード、サブスクリプションや定期支払い、EasyPay や B-Pay の現金支払いコードには対応していません。

注文

注文ステータス

No order yet: 購入者は ePay.bg に移動しましたが支払っていない、通知がまだ届いていない、または ePay.bg がリクエストを拒否もしくは期限切れと報告した状態です。存在するのはカートだけです。

Payment accepted, Delivered or ePay.bg payment on hold: 支払いが確認されました。ステータスは Order Status After Payment に従います。支払いは、トランザクション ID として STAN を付けて記録されます（STAN がない場合は請求書番号）。メモには、請求書番号、支払日、STAN、BORICA コードが表示されます。

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

支払い済みまたは返金済みの注文に対して支払いが届いた場合、ステータスは変更されず、メモで ePay.bg の加盟店パネルで二重払いがないか確認するよう求められます。遅れて届いた拒否または期限切れの通知が支払い済みの注文を変更することはありません。

ePay.bg 支払いブロック

注文ページには ePay.bg payment ブロックが表示され、請求書、リクエストされた金額と通貨、通知の結果、支払日、STAN、BORICA コード、テスト支払い用の Test mode バッジ、注文の ePay.bg notes が含まれます。

返金

ePay.bg の WEB API には返金の呼び出しがないため、PrestaShop からの返金はご利用いただけません。ePay.bg の加盟店パネルで支払いを返金し、PrestaShop で注文を手動で更新してください。

ライセンスキー

このモジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox ePay.bg Gateway は、Modules > Module Manager > VibeFox ePay.bg Gateway > Configure の設定より上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（例えばライセンスの有効期限とドメイン）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-epaybg の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語を含みます）。

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

1 つのキーは 1 つのドメインで使用できます。メインショップのドメインを指し、マルチストア構成でも同様です。ショップからキーを削除しても、そのドメインの枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで ePay.bg は購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、支払い方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認されます。

ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間に、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに ePay.bg が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択したモードの MIN とシークレットキーが設定されていること、カート通貨が BGN、EUR、USD のいずれかであることを確認してください。認証情報が不足していると、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカート通貨、購入者の国、購入者のグループに対して許可されているか確認してください。

支払いは完了したが、注文が作成されなかった: 注文は 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 からのリクエストのみを受け付けます。

支払い後に注文が ePay.bg payment on hold になっている: ePay.bg payment ブロックのメモを読み（注文ステータスを参照）、ePay.bg の加盟店パネルで支払いを確認してから、注文を処理するか支払いを返金してください。

保存時に請求書のプレフィックスが変更された: プレフィックスには数字のみを使用でき、最大 10 桁です。それ以外の文字は削除されます。

開発者向けに、readme ではフック actionEpayBpFormFields（WooCommerce 版の epay_bp_form_fields フィルター）について記載されています。例えば、カード直接入力ページ（PAGE=credit_paydirect）を使用する場合などです。

アンインストール

Modules > Module Manager に移動し、VibeFox ePay.bg Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイ設定とログは削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。ePay.bg の支払い記録と注文ステータス ePay.bg payment on hold は常に保持されるため、再インストール前に開始された支払いも引き続き確認されます。既存の注文は、支払いメモとトランザクション ID を保持します。

ePay.bg は、その所有者の商標です。本モジュールは ePay.bg と提携しておらず、ePay.bg による推奨も受けていません。