VibeFox Eupago for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：8.0 以降。古いバージョンの PHP ではモジュールはインストールされません。

通貨：ユーロ（EUR）。Eupago はユーロのみで請求するため、他の通貨のカートではチェックアウトで決済方法が表示されません。

Eupago アカウント：Eupago チャネルの API キーと、Eupago バックオフィスで作成する Webhook 2.0 のキーが必要です（設定を参照）。本番のバックオフィスは clientes.eupago.pt、サンドボックスのバックオフィスは sandbox.eupago.pt です。サンドボックスと本番は別々のアカウントで、キーも別々です。

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

インストール

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

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

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

4. Eupago チャネルの API キーを入力し、Eupago バックオフィスで Webhook 2.0 を作成して、そのキーを貼り付けます（設定を参照）。

5. Payment Method を選択し、Enable/Disable をオンにして Save をクリックします。サンドボックスモードでテスト注文を行い、その後 Sandbox Mode をオフにします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting Eupago payment と Eupago payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できますが、ユーロはこのモジュールで許可されたままにしておく必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Eupago Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。決済方法が有効なときに現在のモードの API キーが空の場合、ページは項目の上部に警告を表示します（その場合、決済方法はチェックアウトで非表示になります）。サンドボックスモードがオンの間は、Sandbox mode: no real payments are taken. と表示されます。

Eupago

Enable/Disable：Enable Eupago Gateway で決済方法のオン／オフを切り替えます。デフォルト：オフ。

Title：チェックアウトで顧客に表示される決済方法の名前です。注文にも決済方法名として保存されます。デフォルト：Eupago。必須：タイトルが空の場合は Enter a title for the payment method. と表示されます。

Description：チェックアウトで決済方法の下に表示されるテキストです。デフォルト：Pay securely via Eupago.

Payment Method：チェックアウトで提供される Eupago の決済方法は 1 つだけです。

Order Status After Payment：支払いが確認されたときに設定される注文ステータスです。

Eupago アカウント

Eupago バックオフィスで、チャネルの API キーと Webhook 2.0 のキーを取得します：clientes.eupago.pt（本番）または sandbox.eupago.pt（サンドボックス）。サンドボックスと本番は別々のアカウントで、キーも別々です。

Sandbox Mode：sandbox.eupago.pt とサンドボックスのキーを使用します。実際の支払いは発生しません。デフォルト：オン。本番のキーで実際の支払いを受け付けるには、オフにします。オンの間、顧客には決済方法の下に SANDBOX / TEST MODE と表示されます。

Live API Key：本番の Eupago チャネルの API キー（clientes.eupago.pt）。

Live Webhook Key：本番の Webhook 2.0 の暗号化キーです。必須：有効な署名のない通知は拒否されます。

Sandbox API Key：サンドボックスチャネルの API キー（sandbox.eupago.pt）。

Sandbox Webhook Key：サンドボックスの Webhook 2.0 の暗号化キーです。

保存されたキーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

Clear saved keys：キーにチェックを入れて Save をクリックすると、そのキーを削除します。フィールドが空の場合は、保存された値がそのまま残ります。

Webhook URL

Webhook は、支払いが行われたことをショップに通知します。Eupago バックオフィスで、このセクションに表示されている URL、POST メソッド、暗号化の有効化を指定して Webhook 2.0 を作成します。フレンドリー URL を使用している場合、URL は https://your-shop/module/wcp_eupago_gateway/webhook のような形になり、場合によっては /pt/ のような言語コードが付きます。URL は設定画面に表示されたとおりに正確にコピーしてください。サンドボックスのバックオフィスと本番のバックオフィスで、それぞれ 1 つずつ Webhook を作成します。

各 Webhook のキーを Sandbox Webhook Key または Live Webhook Key にコピーします。有効な署名のない Webhook は拒否されます。暗号化されていない Webhook は、Eupago が署名した場合にのみ受け付けられるため、暗号化はオンのままにしてください。通知は、支払いを開始したモードのキーで署名されている必要があります。そのため、サンドボックスの通知が本番の支払いを処理することはありません。モジュールは次の通知ステータスに反応します：

その他のステータスでは対応は不要です。同じ URL に対する Eupago の従来の GET コールバックも受け付けられます。これは API キーで認証され、常に支払いを報告します。通知がない場合、注文が支払い済みになることはありません。モジュールは Eupago に問い合わせず、顧客がショップに戻っても注文は支払い済みになりません。Webhook は、ショップがメンテナンスモードの間も動作し、ショップの国別制限によってブロックされることもありません。

詳細設定

Debug Log：API の呼び出しと通知を、モジュールフォルダー内の logs/eupago_p_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。キー、メールアドレス、電話番号全体は記録されません。エラーは常に記録されます。デフォルト：オフ。

Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると内容が消去されます。

Delete Data on Uninstall：オンの場合、モジュールをアンインストールすると、ゲートウェイの設定、このモジュールの Eupago 支払い記録、およびログが削除されます。注文とその支払いデータは残ります。デフォルト：オフ。

チェックアウト

顧客は支払いステップで決済方法（デフォルトは Eupago）を選び、注文を確定します。その後の動作は Payment Method の設定によって異なります。

Multibanco：チェックアウトで、顧客には You will receive Multibanco payment details after placing the order. と表示されます。モジュールはカート合計に対する Multibanco の参照番号を作成します。注文は、通常の PrestaShop 注文と同様に、直ちに Awaiting Eupago payment の状態で作成され、カートは空になります。注文確認ページには Multibanco Payment Details として、エンティティ、参照番号、金額が表示されます。同じ情報は、注文確認メールの支払い行にも追加されます。顧客は ATM またはホームバンキングで支払います。

MB WAY：チェックアウトで顧客は MB WAY Phone Number を入力します。この欄には請求先住所の電話番号が自動入力されます。ポルトガルの番号は +351 を省略して入力できます。間違った番号を入力すると Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). と表示されます。モジュールは支払いリクエストを MB WAY アプリに送信し、注文を Awaiting Eupago payment の状態で作成します。注文確認ページでは、マスクされた電話番号の MB WAY アプリを開き、5 分以内にリクエストを承認するよう顧客に案内します。

Credit Card：チェックアウトで顧客には You will be redirected to a secure payment page to enter your card details. と表示されます。顧客は Eupago のカード決済ページに移動します。ページの言語は、カートの言語に応じてポルトガル語、スペイン語、英語のいずれかになります。この時点ではまだ注文は存在せず、カートは保持されます。注文は、Eupago が支払いを確認したときにのみ作成されます。顧客が戻ったときに通知がすでに届いていれば、標準の注文確認ページが表示されます。そうでない場合、Payment confirmation ページに Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. と表示され、Check again ボタンが表示されます。カード決済が失敗した場合や中断された場合、顧客は 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. と表示されたチェックアウトに戻ります。

どの方法でも、注文は Eupago が検証済みの通知で支払いを確認した後にのみ支払い済みになります。支払いの詳細は、注文が Awaiting Eupago payment の状態にある間だけ表示されます。その後 Eupago が支払いのキャンセル、期限切れ、または失敗を報告し、注文が支払い済みでなかった場合、注文確認ページには Your Eupago payment was not completed. Please contact us about this order. と表示されます。

Eupago が支払いを開始できない場合、顧客はチェックアウトに残り、短いメッセージが表示されます。例えば The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. です。注文は作成されず、詳細はログに記録されます。他の通貨のカートでは Eupago only supports payments in EUR. と表示されます。

モジュールは、1 つのインストールにつき Eupago の決済方法を 1 つだけ提供します。PrestaShop からの返金、保存済みカード、サブスクリプション、事前承認には対応していません。PayShop、Cofidis Pay、Bizum、その他の Eupago 決済方法、SMS リマインダー、Multibanco の有効期限、ステータスのポーリングにも対応していません。

注文

注文ステータス

No order yet：カード決済が開始されましたが、Eupago はまだ確認していません。カートのみが存在します。

Awaiting Eupago payment：Multibanco の参照番号または MB WAY のリクエストが作成されました。備考には、エンティティと参照番号、またはマスクされた電話番号が表示されます。

Payment accepted or Delivered：支払いが確認されました。ステータスは Order Status After Payment の設定に従います。支払いは、Eupago のトランザクション ID をトランザクション ID として記録され、備考には決済方法、トランザクション ID、参照番号が表示されます。

Eupago payment on hold：Eupago は、金額または通貨が異なる支払い、このカート用に作成されていない参照番号による支払い、またはその間にキャンセルされたか失敗した注文に対する支払い（例えば遅れて支払われた Multibanco の参照番号）を報告しました。備考に理由が記載されます。支払いと在庫を確認し、注文を手動で完了するか、顧客に返金してください。この支払いに関する後続の通知は、お客様の知らないうちに注文を完了させることはありません。

Canceled：待機中の注文の現在の支払い試行について、Eupago が支払いのキャンセルまたは期限切れを報告しました。

Payment error：待機中の注文の現在の支払い試行について、Eupago がエラーを報告しました。

すでに支払い済みの注文について、Eupago が別の支払いを報告した場合（例えば、以前の Multibanco の参照番号も支払われた場合）、注文は変更されません。備考で、二重払いがないか確認し、Eupago バックオフィスで返金するよう求められます。支払い済みの後にキャンセルまたは返金された注文が、支払い通知によって再度開かれることはありません。

Eupago 支払いブロック

注文ページには、カートのすべての支払い試行を示す Eupago payment ブロックが表示されます。日付、決済方法、サンドボックスの支払いを示す Sandbox バッジ、金額、Multibanco のエンティティと参照番号またはマスクされた MB WAY の電話番号、Eupago のトランザクション ID、ステータスが含まれます。注文が Eupago payment on hold の間、このブロックには Manual review の警告が表示されます。その下の Eupago notes には、注文に関するモジュールの備考が新しい順に一覧表示されます。

返金

PrestaShop からの返金は対応していません。Eupago バックオフィスで顧客に返金し、PrestaShop で注文を手動で更新してください。注文ページの標準の PrestaShop 返金ボタンでは、Eupago を経由して返金は行われません。

ライセンスキー

モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Eupago Gateway は、Modules > Module Manager > VibeFox Eupago Gateway > Configure ページで設定の上にある最初のブロックです。License key にキーを貼り付けて Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-eupago の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに Eupago が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの API キーが設定されていることを確認してください（サンドボックスモードでは Sandbox API Key、本番モードでは Live API Key）。カートの通貨は EUR である必要があります。また、Payment > Preferences で、ユーロ、顧客の国、顧客のグループに対してモジュールが許可されている必要があります。Multibanco の場合、注文合計は 1 € から 999,999.99 € の範囲内である必要があります。

支払いは完了したのに、注文が Awaiting Eupago payment のままか、注文が作成されない：Eupago の通知が届かないか、拒否されています。使用しているモードの Eupago バックオフィスで、Webhook 2.0 が存在すること、その URL が Webhook URL に表示されたものと正確に一致すること、メソッドが POST であること、暗号化がオンであることを確認してください。そのキーが対応するフィールド（Sandbox Webhook Key または Live Webhook Key）にあることを確認してください。Debug Log をオンにして、モジュールページの Log フィールドを確認してください。通知がまったく届かない場合は、Eupago バックオフィスで支払いを確認してください。

Webhook が Invalid signature または Missing signature を返す：モジュールの Webhook キーが Webhook のキーと一致していないか、Webhook が暗号化も署名もされていません。キーを再度コピーし、暗号化をオンのままにしてください。

Webhook が Webhook key not configured を返す：どちらの Webhook キーも設定されていません。キーを貼り付けた後、Eupago は通知を再試行します。

Webhook が Decryption failed を返す：署名は有効ですが、本文を復号できませんでした。Eupago バックオフィスの Webhook 2.0 の設定を確認してください。

Webhook が Environment mismatch を返す：通知は、支払いが開始されたモードとは別のモードのキーで署名されています。サンドボックスの通知が本番の支払いを処理することはなく、その逆もありません。サンドボックスキーと本番キーが入れ替わっていないか確認してください。

Webhook が Order not found を返す：通知は、このショップの Eupago 支払いがないカートに関するものです。例えば、同じ Eupago チャネルを使用する別のショップで行われた支払いが該当します。

Webhook が Busy or Retry を返す：カートが同時に別のリクエストで処理されていたか、注文を作成できませんでした（例えば、モジュールが無効になっている場合）。Eupago は通知を再試行します。理由はログに記録されています。

従来のコールバックが Invalid API key を返す：Eupago から送信された API キーが、Live API Key または Sandbox API Key と一致しません。Webhook の URL をブラウザで開いた場合も同じ応答が表示されますが、これは正常です。

顧客に The MB WAY payment could not be started と表示される：電話番号が MB WAY に登録されているか確認し、もう一度お試しください。

支払い後に注文が Eupago payment on hold になっている：Eupago payment ブロックの Eupago notes を確認してください。金額または通貨が異なっていた、参照番号が不明だった、または注文がキャンセルされた後に支払いが届いた可能性があります。Eupago バックオフィスで支払いを確認した後、注文を完了するか、顧客に返金してください。

アンインストール

Modules > Module Manager に進み、VibeFox Eupago Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイの設定、このモジュールの Eupago 支払い記録、およびログが削除されます。オフの場合、すべての設定と記録は、後で再インストールするために保持されます。注文ステータス Awaiting Eupago payment と Eupago payment on hold は常に保持されます。既存の注文は、支払いの備考とトランザクション ID を保持します。

Eupago は、各所有者の商標です。本モジュールは Eupago と提携しておらず、Eupago による推奨もされていません。