VibeFox Eupago for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.0 以降。インストールされ、有効化されていること。

PHP: 8.0 以降。

ストア通貨: ユーロ（EUR）。Eupago はユーロのみ請求するため、それ以外の通貨の場合、チェックアウトで決済方法は表示されません。

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

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_eupago_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます。WooCommerce > Settings > Payments > Eupago > Manage、またはプラグインページのプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。

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

6. Payment Method を選び、Enable/Disable をオンにして、サンドボックスモードでテスト注文を行い、その後 Sandbox Mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Eupago。ゲートウェイを有効にしている場合、現在のモードの API キーが空だと、ページに警告が表示されます（その場合、ゲートウェイはチェックアウトで非表示になります）。サンドボックスモードがオンのときは Sandbox mode: no real payments are taken. と表示されます。決済方法の一覧では、現在のモードの API キーが設定されるまで Eupago に対応が必要という表示になり、サンドボックスモードではテストモードのバッジが表示されます。

一般

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

Title: チェックアウトで購入者に表示される決済方法の名称です。デフォルト: Eupago。

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

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

Order Status After Payment: 支払いが確認されたときに設定される注文ステータスです。Processing（デフォルト）または Completed を選べます。ステータスは即座に設定され、ステータス変更は 1 回、メールは 1 通です。

Eupago アカウント

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

Sandbox Mode: Enable sandbox/test mode を使用すると、sandbox.eupago.pt とサンドボックスのキーが使われます。実際の支払いは発生しません。デフォルト: on。オフにすると、本番のキーで実際の支払いを受け付けます。

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 の暗号化キーです。

Webhook URL

Webhook は、支払いが行われたことをストアに通知します。Eupago バックオフィスで、この設定セクションに表示される URL を指定し、メソッドを POST、暗号化を有効にして Webhook 2.0 を作成します。URL は https://your-site/wc-api/eupago_payment_callback/ のような形式です。サンドボックスのバックオフィスと本番のバックオフィスでそれぞれ 1 つずつ Webhook を作成してください。

各 Webhook のキーを Sandbox Webhook Key または Live Webhook Key にコピーします。有効な署名がない Webhook は拒否されます。暗号化されていない Webhook は、Eupago が署名している場合にのみ受け付けられるため、暗号化はオンのままにしてください。プラグインは、次の通知ステータスに反応します：

それ以外のステータスでは、対応は不要です。同じ URL への Eupago の従来型 GET コールバックも受け付けられます。これは API キーで認証され、常に支払いを報告します。通知がない場合、注文が支払い済みになることはありません。プラグインは Eupago に問い合わせず、購入者がストアに戻っても注文は支払い済みになりません。

詳細設定

Debug Log: Enable logging を有効にすると、API 呼び出しと通知が WooCommerce > Status > Logs に記録されます。ソースは wcp_eupago_gateway です。キー、メール、電話番号全体は記録されません。エラーは常に記録されます。デフォルト: off。

Delete Data on Uninstall: Delete all plugin data when uninstalling。チェックを入れると、プラグインを削除したときにゲートウェイの設定とログが削除されます。注文とその支払いデータは保持されます。デフォルト: off。

チェックアウト

購入者は決済方法（デフォルトは Eupago）を選び、注文します。サンドボックスモードでは、チェックアウトに SANDBOX / TEST MODE と表示されます。その後の動作は Payment Method によって異なります。

Multibanco: チェックアウトで購入者には You will receive Multibanco payment details after placing the order. と表示されます。プラグインは注文合計に対する Multibanco の参照番号を作成します。注文は保留になり、在庫が減り、カートは空になります。注文受付ページには、エンティティ、参照番号、金額とともに 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 アプリに送信します。注文は保留になり、在庫が減り、カートは空になります。注文受付ページでは、MB WAY アプリを開いて 5 分以内にリクエストを承認するよう案内されます。

Credit Card: チェックアウトで購入者には You will be redirected to a secure payment page to enter your card details. と表示されます。購入者は Eupago のカード決済ページに移動します。ページの言語は、サイトの言語に応じてポルトガル語、スペイン語、英語のいずれかになります。注文は決済待ちのままで、カートは保持されます。支払い後、購入者は注文受付ページに戻ります。通知が届くまで、このページには Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. と表示されます。カード決済が失敗したり中断されたりした場合、購入者は Pay for order ページに移動し、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 が検証済みの通知で支払いを確認した後だけです。購入者は Pay for 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. 注文は変わらず、詳細はログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。WooCommerce の High-Performance Order Storage（HPOS）に対応しています。購入者に表示されるテキストはポルトガル語に翻訳されています。

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

注文

注文ステータス

Pending payment: カード決済が開始されましたが、Eupago はまだ確認していません。

On hold, awaiting payment: Multibanco の参照番号、または MB WAY のリクエストが作成されました。注文メモには、エンティティと参照番号、またはマスクされた電話番号が表示されます。

Processing or Completed: 支払いが確認されました。ステータスは Order Status After Payment に従います。注文メモには、決済方法、Eupago のトランザクション ID、参照番号が表示されます。注文のトランザクション ID は、Eupago のトランザクション ID です。

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

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

Failed: 未払い注文の現在の支払い試行について、Eupago がエラーを報告しました。

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

返金: WooCommerce からの返金には対応していません。Eupago バックオフィスで購入者に返金し、Refund manually を使って WooCommerce に返金を記録してください。

ライセンスキー

本プラグインは、vibefox.net で購入した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Eupago の上部にあります。キーを License key に貼り付けて Activate をクリックします。ブロックには、ステータス（ライセンスの有効期限日や、お使いのドメインなど）が表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、Eupago はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、決済方法が (unlicensed — visible to admins only) と付いた状態で引き続き表示されるため、キーを購入する前にプラグインの設定とテストができます。プラグインページと WooCommerce のページにはリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認されます。

ライセンスが期限切れになってもプラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスは、バックグラウンドで自動的に再確認されます。

トラブルシューティング

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

支払いは完了したのに、注文が Pending payment または On hold のまま: Eupago の通知が届かないか、拒否されています。使用しているモードの Eupago バックオフィスで、Webhook 2.0 が存在すること、その URL が設定に表示されたものと完全に一致すること、メソッドが POST であること、暗号化が有効であることを確認してください。そのキーが対応する欄（Sandbox Webhook Key または Live Webhook Key）に入っていることを確認してください。Debug Log を有効にし、WooCommerce > Status > Logs（ソース：wcp_eupago_gateway）を確認してください。通知がまったく届かない場合は、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 を返す: 通知は、注文が行われたモードとは別のモードのキーで署名されています。サンドボックスの通知が本番の注文を支払うことはなく、その逆もありません。

従来型コールバックが Invalid API key を返す: Eupago から送られた API キーが Live API Key または Sandbox API Key と一致しません。

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

支払い後に注文が On hold になる: 注文メモを確認してください。金額または通貨が異なっていた、参照番号が不明だった、または注文がキャンセルされた後に支払いが行われた、のいずれかです。Eupago バックオフィスで支払いを確認し、注文を完了させるか、購入者に返金してください。

ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。例えば、キーが別のドメインで既に使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインのキーを有効化してください。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。

開発者向けに、プラグインのドキュメントではフィルター eupago_p_icon（チェックアウトのアイコン）と eupago_p_card_language（Eupago のカード決済ページの言語：PT、EN、ES）が紹介されています。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とログは、Delete Data on Uninstall がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。注文とその Eupago の参照番号は、常に保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。

Eupago は、それぞれの所有者の商標です。本プラグインは Eupago と提携しておらず、Eupago による推奨も受けていません。