VibeFox Nexi XPay for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

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

PHP: 8.0 以降。

通貨: ストアまたは注文の通貨は EUR である必要があります。他の通貨の場合、チェックアウトで支払い方法は表示されません。

Nexi XPay アカウント: 「Pagamento Semplice」リダイレクト連携の Nexi XPay 加盟店アカウントと、端末のエイリアス（端末 ID）および MAC キーが必要です。テスト用と本番用の認証情報は別々です。テスト用の認証情報は Nexi XPay のテストエリアまたは開発者ポータル（developer.nexi.it）で取得し、本番用の認証情報は加盟店アカウントが有効化された後に Nexi XPay の管理画面で取得します。Nexi 側で設定する必要はありません。通知アドレスはすべての決済とともに送信されます。

公開サイト: 通知 URL はインターネットから到達可能である必要があります。メンテナンスモード、ベーシック認証、Nexi をブロックするファイアウォールのルールがないことを確認してください。そうでない場合でも、購入者の署名付き返却によって決済は確定します。

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

インストール

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

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

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

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

5. Test Mode をオンのままにして、テスト用のエイリアスと MAC キーを入力します（設定の項を参照）。

6. Enable/Disable をオンにして、テスト注文を行います。すべて正常に動作したら、本番用のエイリアスと MAC キーを入力し、Test Mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Nexi XPay。フィールドの上には、テストモードがオンの間 テストモードがオンです：決済は Nexi XPay のテスト環境に送信され、実際の料金は請求されません。 と表示されます。また、ゲートウェイが有効なのに現在のモードのエイリアスまたは MAC キーが空の場合、またはストアの通貨が EUR でない場合には警告が表示されます。どちらの場合も、支払い方法はチェックアウトで非表示になります。貼り付けたキーの前後の空白や改行は、保存時に削除されます。

一般

Enable/Disable: Enable Nexi XPay Gateway は、支払い方法のオン／オフを切り替えます。既定値：オフ。

Title: チェックアウトで購入者に表示される支払い方法の名称。既定値：Credit Card (Nexi)。テストモードでは、チェックアウトの名称に (TEST MODE) が追加されます。

Description: チェックアウトで購入者に表示される支払い方法の説明。既定値：Pay securely with your credit card via Nexi XPay.

テスト環境

テスト決済は int-ecommerce.nexi.it に送信され、実際のカードには請求されません。テスト用のエイリアスと MAC キーは、Nexi XPay のテストエリアまたは開発者ポータル（developer.nexi.it）で取得してください。

Test Mode: Enable test mode は、Nexi XPay のテスト環境とテスト用の認証情報を使用します。チェックを外すと、本番用の認証情報で実際の決済を受け付けます。既定値：オン。

Test Alias: Nexi XPay テスト端末のエイリアス（端末 ID）。

Test MAC Key: Nexi XPay テスト端末の MAC 計算キー。

本番環境

本番用のエイリアスと MAC キーは、加盟店アカウントが有効化された後に Nexi XPay の管理画面（ecommerce.nexi.it）に表示されます。

Live Alias: Nexi XPay 本番端末のエイリアス（端末 ID）。

Live MAC Key: Nexi XPay 本番端末の MAC 計算キー。

決済

通知 URL はすべての決済とともに Nexi に送信されるため、管理画面で設定する必要はありません。このセクションに URL が表示されます。形式は https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id} のようなもので、末尾に注文 ID が付きます。Nexi は決済結果をサーバー間通信でこの URL に送信するほか、購入者の返却時にも渡します。どちらも同じ方法で署名され、決済が行われた環境の MAC キー、その環境のエイリアス、およびその注文に対して発行されたトランザクションコードで検証されます。検証に失敗した結果は拒否され、何も変更されません。

Capture: 代金を請求するタイミング。

Immediate capture: 決済はただちにキャプチャされ、注文は支払い済みになります（既定）。

Deferred capture (authorize only): キャプチャは端末のプロファイルに従います。注文は承認済みとして保留状態になり、注文操作 Capture Nexi XPay payment でキャプチャするか、Nexi の管理画面でキャプチャしてから注文を処理中に変更するまで保留のままになります。

Order Status After Payment: 決済成功後の注文のステータス。ステータスは 1 回のステータス変更と 1 通のメールで、すぐに設定されます。

処理中（WooCommerce の既定）: 既定の設定です。

完了: 支払い済みのすべての注文が完了になります。

保留: 支払い済みのすべての注文は、手動で確認されるまで保留になります。

詳細設定

Debug Log: Enable logging は、決済イベントを WooCommerce > Status > Logs にソース wcp_nexi_gateway として記録します。MAC キー、カード情報、メールアドレスは記録されません。MAC チェックの失敗などのエラーと警告は、このオプションがオフでも常に記録されます。既定値：オフ。

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled。既定値：オフ。

チェックアウト

購入者は支払い方法（既定では Credit Card (Nexi)）を選択し、注文を行います。次のページには Nexi XPay に移動して決済しています... と表示され、購入者は自動的に Nexi XPay のページに移動します。移動しない場合に備えて Pay Now ボタンも表示されます。決済は、新しいトランザクションコード、購入者のメールアドレス、説明 Order、注文番号、およびストア名とともに EUR で送信されます。Nexi のページは、ストアの言語がイタリア語、英語、スペイン語、フランス語、ドイツ語、日本語、中国語、アラビア語、ロシア語、ポルトガル語のいずれかであればその言語で開き、それ以外の場合は英語で開きます。

購入者は決済を行うと、ストアの注文受付ページに戻ります。注文が支払い済みになるのは、注文の金額と通貨が完全に一致する、検証済みの Nexi の結果を受け取った後だけです。サーバー間通知か署名付きの購入者の返却のうち、先に届いた方が使われます。

決済が拒否された場合、または購入者が Nexi のページでキャンセルした場合、購入者はチェックアウト（カートが空の場合は Pay for order ページ）に戻り、次のいずれかのメッセージが表示されます：決済が完了しませんでした。もう一度お試しいただくか、別の支払い方法をお選びください。、決済がキャンセルされました。もう一度お試しください。、または 決済を確認できませんでした。カードに請求が行われている場合は、再度お支払いいただく前にお問い合わせください。。Nexi のページでキャンセルしても注文は変更されないため、購入者は再度支払うことができます。

プラグインが現在のモード向けに設定されていない場合、購入者には この支払い方法は現在ご利用いただけません。別の支払い方法をお選びください。 と表示されます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

プラグインは Nexi XPay のページでのみ決済を受け付けます。WooCommerce からの返金、保存済みカードや OneClick、サブスクリプションや定期決済、Pay-By-Link、XPay Build の埋め込みフィールド、WooCommerce で選択する支払い方法には対応していません。Nexi のページには、端末で有効になっている支払い方法が表示されます。

注文と返金

注文ステータス

支払い待ち: 購入者は Nexi に移動しましたが、まだ支払っていないか、Nexi のページでキャンセルしました。

処理中、完了、保留: Nexi が決済を確認しました。ステータスは Order Status After Payment に従います。注文メモには、承認コード、トランザクションコード、カードブランド、Nexi のメッセージが表示されます。トランザクション ID は Nexi のトランザクションコードです。

保留（承認済み）: 延期キャプチャが選択されており、決済は承認されただけの状態です。注文操作 Capture Nexi XPay payment でキャプチャしてください。

保留（未確定）: Nexi が決済を確認待ちとして報告しました。注文は最終結果によって更新されます。

決済後の保留: Nexi から受け取った金額または通貨が注文と一致しなかった（注文は支払い済みになりません）、または既にキャンセルされた注文に対して決済が成功して届いた場合です。注文メモに理由が記載されます。Nexi XPay の管理画面で決済を確認し、注文を処理するか返金してください。

失敗: 直近の決済試行が拒否、キャンセル、またはエラーで終了しました。購入者は再度支払うことができます。

支払い済みの注文が、後の失敗によって格下げされることはありません。既に支払い済みの注文に別の決済が成功して届いた場合、重複であれば Nexi XPay の管理画面で返金するようメモで通知されます。

延期キャプチャ

承認済みで保留になっている注文は、注文を開き、注文操作で Capture Nexi XPay payment を選択して矢印をクリックします。プラグインは、決済が行われた環境で承認済み金額をキャプチャし、Order Status After Payment のステータスで注文を支払い済みにします。キャプチャに失敗した場合は、エラーが注文画面に表示され、注文メモに追加されます。注文は保留のままになります。

返金

返金は WooCommerce からは行わないため、Refund via ボタンはありません。Nexi XPay の管理画面で返金を行い、その後 WooCommerce に手動で記録してください。

ライセンスキー

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

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

有効なキーがない場合、Nexi XPay はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には この支払い方法は利用できません。別の方法をお選びください。 と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で支払い方法が表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。既に開始された決済は引き続き確認され、延期された決済も引き続きキャプチャできます。

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

トラブルシューティング

チェックアウトに Nexi XPay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの認証情報が両方そろっていること（テストモードでは Test Alias と Test MAC Key、本番モードでは Live Alias と Live MAC Key）、そしてストアまたは注文の通貨が EUR であることを確認してください。この場合、設定ページに警告が表示されます。

決済は完了したが、注文が支払い待ちのまま: 通知も購入者の返却も受け付けられていません。ストアがインターネットから到達可能か、MAC キーとエイリアスが決済の環境（テストまたは本番）と一致しているかを確認し、Debug Log を有効にして、WooCommerce > Status > Logs（ソース wcp_nexi_gateway）で Nexi が送信した内容を確認してください。

通知の応答が invalid_mac または invalid_alias: 設定の MAC キーまたはエイリアスが、結果を送信した端末と一致しません。Nexi のテストエリアまたは管理画面から再度コピーしてください。

通知の応答が unknown_transaction: そのトランザクションコードは、このストアがその注文に対して発行したものではありません。結果は無視されます。

通知の応答が not_configured または busy: 決済の環境のエイリアスまたは MAC キーが空である、または別のリクエストがちょうど注文を更新中でした。Nexi は通知を再送します。

注文が決済後に保留になっている: 注文メモを確認してください。延期キャプチャが選択されている（注文操作で決済をキャプチャする）、金額または通貨が一致しなかった、キャンセル済みの注文に決済が届いた、Nexi で決済が保留になっている、または決済後のステータスとして保留が選択されている、のいずれかです。

Capture Nexi XPay payment が表示されない、または失敗する: この操作は、延期キャプチャで承認済みとして保留になっている Nexi の注文にのみ表示されます。失敗した場合は、注文メモのエラーを確認してください。キャプチャは、決済が行われた環境のキーを使用します。

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

アンインストール

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

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