VibeFox Niubiz for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。古い PHP バージョンではモジュールをインストールできません。
通貨: ペルー・ソル（PEN）または米ドル（USD）。この決済方法は、これらの通貨のいずれかのカートに対してのみ表示されます。その他の通貨の場合、チェックアウトでは非表示になります。
Niubiz アカウント: Niubiz は環境ごとに加盟店 ID（código de comercio）、API user、API password を発行します。サンドボックスの認証情報は Niubiz の統合チームから提供され、本番の認証情報は Niubiz が統合を認定した後に提供されます。Webhook の設定は不要です。Niubiz は承認にすぐ応答します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ有効です。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で確認する場合は、モジュール一覧で VibeFox Niubiz Payment を探して Configure をクリックします。
3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーの項を参照）。
4. Sandbox mode をオンのままにして、サンドボックスの merchant ID、API user、API password を入力します（設定の項を参照）。
5. Enable/Disable をオンにして Save をクリックし、Niubiz のテストカードで数回テスト決済を行います。
6. Niubiz が統合を認定したら、本番の認証情報を入力し、Sandbox mode をオフにします。
インストール時に、モジュールは注文ステータス Niubiz payment on hold を作成します。PrestaShop は新しい決済モジュールを、その時点で有効なすべての通貨、すべての顧客グループ、有効な国に関連付けます。これは Payment > Preferences で変更できます。そこで、このモジュールに PEN または USD が許可されていることを確認してください。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Niubiz Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部には、ストアで有効な PEN または USD 通貨がない場合、または現在のモードの認証情報が不完全な場合に警告が表示されます（いずれの場合も、チェックアウトでは決済方法が非表示になります）。ストアの既定の通貨が PEN でも USD でもない場合、ページには Niubiz は PEN または USD のカートに対してのみ提供されると表示されます。サンドボックスモードがオンの間、ページには サンドボックスモードがオンです：決済は Niubiz のサンドボックスに送られ、実際の請求は行われません。 と表示されます。
Niubiz
Enable/Disable: Enable Niubiz payments で決済方法のオン／オフを切り替えます。デフォルト：オフ。
Title: チェックアウト時に購入者が見る決済方法の名称です。注文にも決済方法の名称として保存されます。デフォルト：Credit or debit card (Niubiz)。必須：空のタイトルは保存されず、以前のタイトルが保持されます。
Description: チェックアウト時に決済方法の下に表示されるテキストです。デフォルト：Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.
Niubiz 認証情報
Niubiz は、サンドボックス用に merchant ID、API user、API password を発行し、認定後には本番用も発行します。開発者向けドキュメントは desarrolladores.niubiz.com.pe にあります。
Sandbox mode: Niubiz のサンドボックス（QA）環境を使用します。実際の請求は行われません。API のエンドポイントと、下記の認証情報のセットの両方が切り替わります。デフォルト：オン。実際の決済を行う場合はオフにしてください。オンの間、購入者には決済方法の下と支払いページに サンドボックスモード：Niubiz のテストカードを使用してください — 実際の請求は行われません。 と表示されます。
Sandbox merchant ID: サンドボックスアカウントの加盟店コードです。数字のみ。スペースは削除されます。値に他の文字が含まれている場合、ページにエラーが表示され、以前の値が保持されます。他のフィールドは保存されます。
Sandbox API user: サンドボックスの API user です。
Sandbox API password: サンドボックスの API password です。
Production merchant ID: 本番（加盟店契約済み）アカウントの加盟店コードです。数字のみで、同じチェックが行われます。
Production API user: 本番の API user です。
Production API password: 本番の API password です。
保存済みのパスワードは再度表示されません。フィールドは空のままで、保存済み — 変更しない場合は空のままにしてください。 と表示されます。変更する場合にのみ新しい値を入力してください。
Clear saved passwords: パスワードにチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は保存された値が保持されます。
決済フォーム
Logo URL: Niubiz の決済フォームに表示されるロゴの任意の HTTPS アドレスです（約 187 × 40 px）。未設定の場合はストア名が表示されます。有効な https:// アドレスでないものはエラーで拒否され、以前の値が保持されます。
詳細設定
Debug log: Niubiz API の呼び出しを、モジュールフォルダ内の logs/niubiz_p_debug.log.php に記録します。このファイルは Web から開けません。エラーと警告は、このスイッチがオフでも常に記録されます。認証情報、トークン、カードや購入者のデータは記録されません。デフォルト：オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Delete data on uninstall: オンにすると、モジュールをアンインストールした際に設定とログが削除されます。注文に保存された決済データ（Niubiz の試行記録、注文メモ）と注文ステータスは、常に保持されます。デフォルト：オフ。
チェックアウト
支払いステップで、購入者は決済方法（デフォルトは Credit or debit card (Niubiz)）を選び、注文を確定します。モジュールは Niubiz にアクセストークンを要求し、カートの通貨でカート合計の決済セッションを作成して、ストアの Niubiz payment 支払いページを開きます。この時点ではまだ注文は存在しません。
支払いページでは Niubiz の決済フォームが自動的に開きます。ページには 安全な Niubiz 決済フォームで支払いを完了してください — カード情報は、このサイトではなく Niubiz に入力されます。 と表示されます。また、フォームを再度開くためのカート合計を表示した Pay ボタンと、Choose another payment method のリンクがあります。JavaScript が必要です。Niubiz のフォームを読み込めない場合、ページには Niubiz の決済フォームを読み込めませんでした。ページを再読み込みするか、後でもう一度お試しください。 と表示されます。
購入者は Niubiz のフォームにカード情報を入力します。Niubiz はストアに一度限りのトークンを返し、モジュールはそのトークンを、セッションの金額、通貨、購入番号とともにサーバー上で承認します。承認は、セッションが作成された環境で行われます。決済はすぐに請求されます。注文が支払い済みになるのは、Niubiz が決済を承認し、その応答がカートと一致した場合だけです。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。
カードが拒否された場合: 注文は作成されません。購入者は Your payment was declined: と Niubiz の理由とともに支払いページに戻り、同じカードまたは別のカードで再試行できます。フォームはメッセージの上では再度開かれません。購入者は Pay をクリックします。
Niubiz から応答がない場合: Niubiz が確定的な応答を返さない場合（タイムアウト、サーバーエラー、読み取れない応答）、注文は Niubiz payment on hold で作成され、確認ページには Niubiz での決済を確認できませんでした。再度お支払いにならないでください。ストアが決済を確認し、ご連絡いたします。 と表示されます。Niubiz がカートと一致しない決済を承認した場合、ページには 決済を受け付け、ストアで確認中です。その他に必要な場合はご連絡いたします。 と表示されます。
リクエストが拒否された場合: Niubiz がリクエスト自体を拒否した場合（例：認証情報が無効、または購入番号が重複している場合）、注文は作成されず、購入者には Niubiz で決済を処理できず、カードには請求されていません。 と表示されます。理由はログに記録されます。
カートが変更された場合: フォームを開いた後にカート合計が変わった場合（例：ブラウザの別のタブで変更した場合）、決済は承認されず、購入者には 決済フォームを開いた後にカートが変更されたため、カードには請求されていません。合計を確認してから、もう一度お支払いください。 と表示されます。
セッションの有効期限切れ: Niubiz の決済セッションは最大 20 分間有効です。セッションが既に使用されている場合、残り時間が 5 分未満の場合、別のモードまたは別の加盟店 ID に属する場合、またはカート合計が変更された場合、支払いページは新しいセッションを作成します。
決済を試行するたびに新しい購入番号が割り当てられます。カート ID の後に 3 桁の試行番号（最大 12 文字）が付きます。Niubiz は承認ごとに一意の購入番号を要求するためです。
本モジュールは 1 回限りのカード決済のみに対応しています。PrestaShop からの返金やキャンセルには対応していません。保存済みカード、サブスクリプションや定期決済、分割払い（cuotas）の選択、PagoEfectivo、Yape、その他のウォレットや QR 決済にも対応していません。応答が失われたために保留になった注文は、自動では再確認されません。
注文
注文ステータス
No order yet: 購入者は支払いページにおり、まだ支払っていないか、カードが拒否されたか、リクエストが拒否されました。カートだけが存在します。拒否や却下の記録はモジュールのログに書き込まれます。
Payment accepted: Niubiz が決済を承認し、その応答がカートと一致しました。決済は Niubiz のトランザクション ID とともに記録され、メモには環境、トランザクション ID、承認コード、購入番号、マスクされたカード番号付きのカードブランドが表示されます。
Niubiz payment on hold, approved but not matching: Niubiz が、購入番号、金額、通貨がカートと異なる決済、または応答に金額や通貨が含まれていない決済を承認しました。注文は支払い済みにはなりません。承認がカートの通貨で行われた場合、承認された金額は、そのトランザクション ID を持つ決済として記録されます。メモには相違点が一覧表示されます。Niubiz の管理コンソールでトランザクションを確認してください。
Niubiz payment on hold, no definitive answer: Niubiz が明確な応答を返さなかったため、カードに請求された可能性があります。決済は記録されません。メモには購入番号が記載されています。Niubiz の管理コンソールで検索してください。トランザクションが承認されていて正しければ、注文を Payment accepted に設定し、そうでなければキャンセルしてください。
すでに注文があるカートに対して 2 回目の決済の応答が届いた場合、2 つ目の注文は作成されません。注文のメモには購入番号、トランザクション ID、金額が記載されるため、Niubiz の管理コンソールで確認し、必要に応じて返金または取り消しができます。
Niubiz 決済ブロック
注文ページには、購入番号、環境（サンドボックスまたは本番）、トランザクション ID、承認コード、カード情報、注文のメモを含む Niubiz payment ブロックが表示されます。Niubiz payment on hold の注文の場合、このブロックは Niubiz の管理コンソールで購入番号を確認するよう促します。このブロックは読み取り専用です。
返金
返金とキャンセルは PrestaShop からは行えません。Niubiz の管理コンソールでトランザクションを返金または取り消し、注文を手動で更新してください。注文ページにある PrestaShop の標準の返金ボタンでは、Niubiz を通じて資金は返還されません。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Niubiz Payment は、Modules > Module Manager > VibeFox Niubiz Payment > Configure ページの最上部にあるブロックで、設定の上に表示されます。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日や、ご利用のドメインなど）、そして次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下には Product: presta-payment-niubiz の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントを開きます。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員のみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックには理由が表示されます。例：キーが見つかりません、このキーは別の製品のものです、ドメインの上限に達しました、または日付付きの ライセンスの有効期限が切れました。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインでのみ有効です。メインストアのドメインを指し、マルチストア構成でも同様です。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで Niubiz は購入者に表示されません。それでも決済が開始された場合、購入者には この決済方法は利用できません。別の方法を選択してください。 と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、決済方法はご自身にも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認されます。
ライセンスの有効期限が切れた場合もモジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Niubiz が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの merchant ID、API user、API password が入力されていること（サンドボックスモードではサンドボックスのフィールド、それ以外では本番のフィールド）、そしてカートの通貨が PEN または USD であることを確認してください。認証情報または通貨が正しくない場合、設定ページに警告が表示されます。Payment > Preferences で、このモジュールがカートの通貨、顧客の国、顧客のグループに対して許可されているか確認してください。
決済は成功したが、注文が作成されていない: Niubiz はこの決済フォームに対して Webhook を提供していないため、注文は承認の応答によってのみ作成されます。購入者がフォームを完了しなかった場合、注文はありません。そうでない場合は、モジュールページの Log フィールドを確認し、Niubiz の管理コンソールで購入番号を検索してください。Niubiz が応答したものの注文を作成できなかった場合（例：モジュールが無効になっていた場合）、購入者には 決済は受け付けられましたが、注文を自動で完了できませんでした。お問い合わせください — 再度お支払いにならないでください。 と表示され、購入者が支払いページを再度開くと、モジュールは注文の作成を再試行します。
購入者に「We could not connect to Niubiz」と表示される: アクセストークンを取得できませんでした。現在のモードの API user と API password を確認し、サーバーから Niubiz の API に接続できることを確認してください。詳細は Debug log をオンにして確認できます。
購入者に「We could not start the Niubiz payment」と表示される: Niubiz が決済セッションを作成しませんでした。現在のモードの merchant ID とログを確認してください。
購入者に「This payment attempt was already processed」と表示される: 同じフォームが 2 回送信されました。購入者は支払いページで決済をやり直します。カードは 2 回請求されません。
購入者に「This order is already being paid」と表示される: 別のリクエストが、今まさに同じカートを承認しています。購入者はしばらく待ち、メールを確認してから再試行してください。
ログに「Niubiz reported a duplicate authorization」と表示される: Niubiz はこの購入番号をすでに把握しています。Niubiz の管理コンソールで確認してください。購入者は新しい購入番号で再試行できます。
注文が Niubiz payment on hold になっている: Niubiz payment ブロックのメモを確認してください。Niubiz が確定的な応答を返さなかったか、カートと一致しない決済を承認しました。Niubiz の管理コンソールで購入番号を検索し、注文を Payment accepted に設定するか、キャンセルしてください。
設定の保存時のエラー: merchant ID は数字のみで構成され、ロゴの URL は有効な https:// アドレスである必要があります。以前の値が保持されます。
開発者向け：Niubiz が加盟店固有の不正検知フィールド（MDD）の送信を求める場合、別のモジュールがフック actionNiubizPMerchantDefineData でそれらを追加できます。決済セッションとともに送信されるカード名義人のデータは、フック actionNiubizPCardholderData で変更できます。
アンインストール
Modules > Module Manager に移動し、VibeFox Niubiz Payment の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合は、後で再インストールするためにすべての設定が保持されます。Niubiz の決済試行記録（購入番号、環境、トランザクション ID）と注文ステータス Niubiz payment on hold は、決済履歴として常に保持されます。既存の注文は、決済メモとトランザクション ID を保持します。
Niubiz は、それぞれの所有者の商標です。本モジュールは Niubiz とは提携しておらず、Niubiz による承認も受けていません。