VibeFox Nexi XPay for PrestaShop — ヘルプ
要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。
通貨：カートの通貨は EUR である必要があります。それ以外の通貨では、チェックアウト時にこの支払い方法は表示されません。
Nexi XPay アカウント：Nexi XPay の加盟店アカウント（「Pagamento Semplice」リダイレクト連携）と、端末のエイリアス（端末 ID）および MAC キーが必要です。テスト用と本番用の認証情報は別々です。テスト用の認証情報は Nexi XPay のテスト環境または開発者ポータル（developer.nexi.it）で取得し、本番用の認証情報は加盟店アカウントが有効化された後に Nexi XPay の管理画面で取得します。Nexi の管理画面で設定する必要はありません。通知アドレスは決済ごとに送信されます。
公開サイト：通知 URL はインターネットからアクセス可能である必要があり、Nexi をブロックするベーシック認証やファイアウォールのルールがあってはなりません。ショップのメンテナンスモードでもブロックされません。通知がショップに届かなくても、署名付きの顧客の戻りによって支払いは確定します。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Nexi XPay Gateway を見つけて Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーの項を参照）。
4. Test Mode をオンのままにして、テスト用のエイリアスと MAC キーを入力します（設定の項を参照）。
5. Enable/Disable をオンにし、Save をクリックして、テスト注文を行います。すべて正常に動作したら、本番用のエイリアスと MAC キーを入力し、Test Mode をオフにします。
インストール時に、モジュールは二つの注文ステータスを作成します：Awaiting Nexi XPay payment と Nexi XPay payment on hold。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。モジュールのインストール後にショップで有効にした国も、そこでチェックを入れる必要があります。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。テストモードがオンの間、フィールドの上に Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. と表示されます。ゲートウェイが有効なのに現在のモードのエイリアスや MAC キーが空の場合、またはショップの既定の通貨が EUR でない場合は、警告が表示されます。この場合、チェックアウト時に支払い方法は表示されません。貼り付けた値の前後にある空白や改行は、保存時に削除されます。
Nexi XPay
Enable/Disable：Enable Nexi XPay Gateway で支払い方法のオン／オフを切り替えます。既定値：off。
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：Nexi XPay のテスト環境とテスト用の認証情報を使用します。本番用の認証情報で実際の決済を受け付けるには、オフにします。既定値：on。
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 計算キーです。
保存済みの MAC キーは再び表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
保存された秘密情報の削除：Test MAC Key または Live MAC Key にチェックを入れて Save をクリックすると、保存済みのキーを削除できます。空欄の場合は保存済みの値が維持されます。
決済
Notification URL：参考用に表示されます。決済ごとに Nexi へ送信されるため、Nexi の管理画面で設定する必要はありません。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart} のような形式になり、/it/ などの言語コードが含まれることもあり、末尾にカート番号が付きます。Nexi は決済結果をこの URL にサーバー間で送信し、顧客の戻りにも含めて渡します。どちらも同じ方法で署名され、決済が行われた環境の MAC キー、その環境のエイリアス、そのカート向けに発行されたトランザクションコードを使って検証されます。検証に失敗した結果は拒否され、何も変更されません。
キャプチャ：代金をいつ引き落とすか。
Order Status After Payment：支払いが成功した後の注文のステータスです。
詳細設定
Debug Log：決済イベントをモジュールフォルダー内の logs/nexi_ip_debug.log.php に記録します。このファイルは Web から開くことはできません。MAC キー、MAC 値、カードデータ、メールアドレスは記録されません。MAC 検証の失敗などのエラーや警告は、このオプションがオフでも常に記録されます。既定値：off。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Delete Data on Uninstall：オンにすると、モジュールをアンインストールしたときにモジュールの設定とログがすべて削除されます。注文に含まれる Nexi XPay の決済データと注文ステータスは残ります。既定値：off。
チェックアウト
支払い手続きで、顧客は支払い方法（既定では Credit Card (Nexi)）を選んで確定します。次のページには Redirecting to Nexi XPay for payment... と表示され、顧客は自動的に Nexi XPay のページへ移動します。代替として Pay Now ボタンも表示されます。決済は、カート合計額を EUR で、新しいトランザクションコード、顧客のメールアドレス、説明 Cart、カート番号、およびショップ名とともに送信されます。Nexi のページは、カートの言語がイタリア語、英語、スペイン語、フランス語、ドイツ語、日本語、中国語、アラビア語、ロシア語、ポルトガル語のいずれかであればその言語で開き、それ以外の場合は英語で開きます。この時点ではまだ注文は存在しません。
顧客は決済を済ませて、ショップに戻ります。注文が支払い済みになるのは、カートの金額と通貨が完全に一致する、検証済みの Nexi の結果を受け取った後だけです。結果は、サーバー間の通知または署名付きの顧客の戻りのうち、先に届いた方から取得されます。その後注文が作成され、顧客には標準の注文確認ページが表示されます。そこには Your Nexi XPay payment has been received. と書かれています。Nexi が決済を保留中と報告した場合は、Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. と表示されます。保留状態（延期キャプチャまたは手動確認）の注文の場合は、We have received your Nexi XPay payment authorization. Your order will be processed shortly. と表示されます。保留中の決済がその後失敗した場合は、The payment was not completed. Please contact us. と表示されます。
顧客が戻ったときに結果がまだ処理されていなければ、We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. というメッセージと Check again ボタンが表示されるページが開きます。通知が届き次第、注文が作成されます。
決済が拒否された場合や、顧客が Nexi のページでキャンセルした場合は、チェックアウトに戻り、次のいずれかのメッセージが表示されます：The payment was not completed. Please try again or choose a different payment method.、Payment was cancelled. Please try again.、または We could not confirm the payment. If your card was charged, please contact us before paying again.。注文は作成されず、カートは保持されるため、顧客は再度支払うことができます。カートにすでに注文がある場合（例：別のタブで支払い済みの場合）は、新たな支払いではなく注文確認ページに案内されます。
モジュールが現在のモード向けに設定されていない場合、顧客には This payment method is not available right now. Please choose another payment method. と表示されます。
通知は、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。
モジュールは Nexi XPay のページでのみ決済を受け付けます。PrestaShop からの返金、保存済みカードや OneClick、サブスクリプションや定期決済、Pay-By-Link、XPay Build の埋め込みフィールド、PrestaShop で選択された支払い方法には対応していません。Nexi のページには、端末で有効になっている支払い方法が表示されます。
注文と返金
注文ステータス
まだ注文はありません：顧客は Nexi に送られたものの、未払い、キャンセル、または拒否されたか、Nexi がまだ決済を確認していません。存在するのはカートだけです。
Payment accepted, Delivered or Nexi XPay payment on hold：Nexi が決済を確認しました。ステータスは Order Status After Payment に従います。決済は Nexi のトランザクションコードをトランザクション ID として記録され、メモには承認コード、トランザクションコード、カードブランド、Nexi のメッセージが表示されます。
Nexi XPay payment on hold（authorized）：延期キャプチャが選択されており、決済は承認されただけです。注文ページの Capture Nexi XPay payment でキャプチャしてください。
Awaiting Nexi XPay payment：Nexi は決済が確認待ちであると報告しました。注文は最終結果によって更新されます。
Nexi XPay payment on hold after payment：Nexi から受け取った金額または通貨がカートと一致しなかった（注文は支払い済みになりません）か、すでにキャンセルされた注文に対して成功した決済が届きました。メモに理由が記載されます。Nexi XPay の管理画面で決済を確認し、注文を処理するか返金してください。
決済エラー：保留中の決済が失敗しました。同じカートは再度支払うことができないため、顧客は新しい注文を出す必要があります。
支払い済みの注文が、その後の失敗によって格下げされることはありません。すでに支払い済みの注文に対して別の成功した決済が届いた場合は、重複であれば Nexi XPay の管理画面で返金するよう、メモで通知されます。
Nexi XPay 決済ブロック
注文ページには Nexi XPay payment ブロックが表示されます。このブロックには、トランザクションコード（codTrans）、ステータスと Nexi の結果、キャプチャモード、Nexi に送信された金額と受け取った金額、承認コード、カードブランド、Nexi のメッセージと日付、テスト決済用の Test environment バッジ、注文の Nexi XPay notes が含まれます。
延期キャプチャ
保留中の承認済み注文について、ブロック内の Capture Nexi XPay payment をクリックし（ボタンには金額が表示されます）、Capture the authorized amount through Nexi XPay? の確認に応じてください。注文を編集する権限が必要です。モジュールは、決済が行われた環境で、その環境のキーを使って承認済みの金額をキャプチャし、決済を記録して、Order Status After Payment に従ってステータスを設定します。キャプチャに失敗した場合は、ブロックにエラーが表示され、メモが追加され、注文は保留のままになります。同じ決済の二度目のキャプチャは拒否されます。
返金
返金は PrestaShop からは行われないため、Nexi XPay 用の返金ボタンはありません。Nexi XPay の管理画面で返金を行い、その後 PrestaShop に手動で記録してください。注文ページにある PrestaShop の標準の返金ボタンでは、Nexi を通じて返金されることはありません。
ライセンスキー
モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Nexi XPay Gateway は Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure ページの最上部、設定より上にあります。License key にキーを入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やドメインなど）、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-nexi の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウト時に Nexi XPay は顧客に表示されません。それでも決済が開始された場合、顧客には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、支払い方法はあなたに対しても非表示になります。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、承認済みの決済はキャプチャできます。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面で作業している間に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに Nexi XPay が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードで両方の認証情報があること（テストモードでは Test Alias と Test MAC Key、本番モードでは Live Alias と Live MAC Key）、そしてカートの通貨が EUR であることを確認してください。これらの場合、設定ページに警告が表示されます。Payment > Preferences で、モジュールが EUR、顧客の国、顧客のグループに対して許可されているかを確認してください。
決済は完了したのに注文が作成されない：通知も顧客の戻りも受け付けられていません。ショップがインターネットから到達可能であること、MAC キーとエイリアスが決済の環境（テストまたは本番）と一致していること、そして Debug Log をオンにしてモジュールページの Log フィールドで Nexi が送信した内容を確認してください。
通知が invalid_mac または invalid_alias を返す：設定の MAC キーまたはエイリアスが、結果を送信した端末と一致しません。Nexi のテスト環境または管理画面から再度コピーしてください。
通知が unknown_transaction を返す：そのトランザクションコードは、そのカートに対して本ショップが発行したものではありません。結果は無視されます。
通知が not_configured または busy を返す：決済の環境のエイリアスまたは MAC キーが空である、別のリクエストが同時に注文を更新していた、または注文を作成できなかった（例：モジュールが無効）のいずれかです。Nexi は通知を再試行します。
通知 URL をブラウザで開くと method_not_allowed と表示される：これは正常です。この URL は Nexi からのリクエストのみを受け付けます。
注文が Nexi XPay payment on hold after payment になっている：注文ブロック内の Nexi XPay notes を確認してください。延期キャプチャが選択されている（ボタンで決済をキャプチャしてください）、金額または通貨が一致しなかった、キャンセル済みの注文に対して決済が届いた、または支払い後のステータスとして Nexi XPay payment on hold が選択されている、のいずれかです。
Capture Nexi XPay payment が表示されない、または失敗する：このボタンは、延期キャプチャで承認済みとして保留になっている Nexi XPay の注文に対してのみ表示され、注文を編集できる従業員にのみ表示されます。決済の環境のエイリアスまたは MAC キーが空の場合、ブロックにその旨が表示されます。キャプチャに失敗した場合は、ブロックとメモのエラーを確認してください。例：Nexi のコードとメッセージを伴う Nexi XPay refused the capture。
テスト決済では本番の決済が確認されない：各決済は、開始された環境のキーで検証されます。Test Mode を希望するモードに切り替え、そのモードのエイリアスと MAC キーを使用してください。
アンインストール
Modules > Module Manager に進み、VibeFox Nexi XPay Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは必ず削除されます。Delete Data on Uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合は、後で再インストールできるようすべての設定が保持されます。注文の Nexi XPay 決済データと、注文ステータスの Awaiting Nexi XPay payment および Nexi XPay payment on hold は常に保持されるため、再インストール後も承認済みの決済をキャプチャできます。既存の注文は、決済メモとトランザクション ID を保持します。
Nexi および XPay は、それぞれの所有者の商標です。本モジュールは Nexi とは提携しておらず、Nexi による推奨も受けていません。