VibeFox Niubiz for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

通貨: ペルー・ソル（PEN）または米ドル（USD）を System > Localisation > Currencies で有効にしておく必要があります。この支払い方法は、購入者がこれらの通貨のいずれかで支払う場合にのみ提供されます。それ以外の通貨の場合は、チェックアウト時に表示されません。

Niubiz アカウント: Niubiz は、環境ごとに加盟店 ID（código de comercio）、API ユーザー、API パスワードを発行します。サンドボックスの認証情報は Niubiz の連携チームから、本番の認証情報は Niubiz による連携の認定後に提供されます。Webhook の設定は不要です。Niubiz は承認にすぐ応答します。

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで展開してください。README.txt、OpenCart 3 用パッケージ wcp_niubiz_payment-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_niubiz_payment.ocmod.zip が含まれています。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで共通です。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_niubiz_payment-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更はないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Niubiz Payment を探し、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、支払い拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。

4. Sandbox mode をオンのままにして、サンドボックスの加盟店 ID、API ユーザー、API パスワードを入力します（Configuration を参照）。

5. Enable/Disable をオンにして Save をクリックし、Niubiz のテストカードを使って数回テスト決済を行います。

6. Niubiz による連携の認定後、本番の認証情報を入力し、Sandbox mode をオフにします。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_niubiz_payment.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Niubiz Payment を探して Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと Niubiz の認証情報を入力し、OpenCart 3 の手順 3 から 6 と同様に決済をテストします。設定ページとそのフィールドは両方のバージョンで同じです。

新規インストール時は、支払い方法がオフ、サンドボックスモードがオンの状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体を保存します。設定の上部には、ストアで PEN または USD の通貨が有効になっていない場合、または現在のモードの認証情報が不完全な場合に警告が表示されます（どちらの場合も、チェックアウトで支払い方法は非表示になります）。ストアの既定の通貨が PEN でも USD でもない場合、Niubiz は購入者が PEN または USD で支払う場合にのみ提供される旨が表示されます。サンドボックスモードがオンの間、ページには Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. と表示されます。拡張機能を変更する権限がない場合は、設定は表示されますが保存できません。

保存時に、誤った値は保存されません。設定の上部にエラーが表示され、そのフィールドは以前の値に戻り、他のフィールドは保存されます。これは、空または 128 文字を超える Title、数字以外を含む加盟店 ID、https:// で始まらないロゴ URL、整数ではない Sort Order、0 以上の数値ではない Total に当てはまります。

Niubiz

Enable/Disable: Niubiz 決済のオン・オフを切り替えます。既定値: off。

Title: チェックアウトで購入者に表示される支払い方法の名称です。注文にも、この支払い方法の名称として保存されます。既定値: Credit or debit card (Niubiz)。必須、128 文字まで。

Description: Confirm Order のステップで、確認ボタンの上に購入者に表示されるテキストです。既定値: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Sort Order: チェックアウト時の支払い方法の中での Niubiz の表示順です。空欄のままにするか、整数を入力します。

Geo Zone: 選択した地理的ゾーン内の支払い先住所に対してのみ Niubiz を提供します。既定値: All zones。地理的ゾーンは System > Localisation > Geo Zones で設定します。OpenCart 4 では、ストアが支払い先住所を求めない場合、配送先住所が使用されます。

Total: Niubiz を提供するために注文が達している必要がある、ストアの既定の通貨でのチェックアウト合計金額です。空欄のままにすると、どの金額でも Niubiz を提供します。

Niubiz の認証情報

Niubiz は、サンドボックス（QA）用と、認定後の本番用に、加盟店 ID、API ユーザー、API パスワードを提供します。すでに開始された決済は、常にそのモードの認証情報で承認されます。

Sandbox mode: Niubiz のサンドボックスを使用し、実際の請求は行いません。API のエンドポイントと、下記の認証情報の組の両方が切り替わります。既定値: on。本番の認証情報で実際の決済を受け付けるには、オフにします。オンの間は、購入者は Confirm Order のステップと決済ページで SANDBOX MODE: use Niubiz test cards — no real charges are made. と表示されます。

Sandbox merchant ID: サンドボックスアカウントの加盟店コード（código de comercio）です。数字のみ。空白は削除されます。

Sandbox API user: サンドボックスの API ユーザーです。通常はメールアドレスです。

Sandbox API password: サンドボックスの API パスワードです。

Production merchant ID: 本番（提携）アカウントの加盟店コードです。数字のみ。

Production API user: 本番の API ユーザーです。

Production API password: 本番の API パスワードです。

保存済みの API パスワードは再表示されず、ブラウザにも送信されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力します。保存済みのパスワードを削除するには、フィールドの下にある Clear the saved password on save にチェックを入れ、Save をクリックします。

決済フォーム

Logo URL: Niubiz の決済フォームに表示される、ロゴの任意のアドレスです。https:// で始まるアドレスである必要があります。空欄のままにすると、ストア名が表示されます。

注文

OpenCart は、Confirm Order のステップで、ステータスのない注文（欠落注文）を作成します。注文が状態を持つのは、Niubiz が承認に応答した後だけです。以下の各フィールドには、お使いの OpenCart の注文ステータスが表示されます。

Order Status After Payment: Niubiz が決済を承認し、購入番号、金額、通貨が注文と一致しています。既定値: Processing。

On Hold Status: Niubiz が注文と一致しない決済を承認したか、明確な回答を返さなかったため、カードに請求された可能性があります。既定値: Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

詳細設定

Debug log: Niubiz API のリクエストと決済のステップを、OpenCart のログフォルダ（storage/logs）内の niubiz_p_debug.log.php に書き込みます。このファイルはウェブから開くことはできず、5 MB に達すると niubiz_p_debug.old.log.php に移動されます。このスイッチがオフであっても、エラーと警告は常に記録されます。パスワード、トークン、カードやお客様のデータは決してログに記録されません。既定値: off。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。

Delete data on uninstall: オンにすると、拡張機能のアンインストール時にゲートウェイの設定とログが削除されます。注文の Niubiz 決済情報（購入番号、トランザクション ID）は常に保持されます。既定値: off。

インポート / エクスポート

Export: Download JSON は、設定を JSON ファイルとして保存します。API パスワードはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの API パスワードは保持されます。

チェックアウト

Payment Method のステップで、購入者は支払い方法を選択します（既定では Credit or debit card (Niubiz)）。Confirm Order のステップで、購入者にはお客様が設定した説明と、You will complete the payment in the secure Niubiz payment form. という注記が表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。OpenCart 4 では、購入者は支払い方法ブロックの Choose ボタンをクリックし、ウィンドウ Payment method options で支払い方法を選択して、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は注文の通貨で注文合計金額の決済セッションを作成するよう Niubiz にアクセストークンを要求し、ストアの Niubiz payment ページを開きます。セッションを作成できない場合、購入者は Confirm Order のステップに留まり、例えば We could not connect to Niubiz. Please try again in a few minutes. という短いメッセージが表示されます。

決済ページでは、Niubiz の決済フォームが自動的に開きます。ページには Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. と表示されます。また、注文合計金額が表示された Pay ボタンでフォームを再度開くことができ、Choose another payment method のリンクでチェックアウトに戻ることもできます。JavaScript が必要です。Niubiz のフォームを読み込めない場合、ページには The Niubiz payment form could not be loaded. Please reload the page or try again later. と表示されます。

購入者は Niubiz のフォームにカード情報を入力します。Niubiz はストアに一回限りのトークンを返し、拡張機能はセッションの金額、通貨、購入番号を使って、セッションが作成された環境でサーバー側の承認を行います。決済は直ちに請求されます。注文が決済済みとしてマークされるのは、Niubiz が確認し、応答が注文と一致した後だけです。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールと在庫の更新が行われ、購入者には OpenCart の注文完了ページが表示されます。

カードが拒否された場合: 注文はステータスなしのままで、注文にはメモが追加されます。購入者は Your payment was declined: と、Niubiz からの理由とともに決済ページに戻り、同じカードまたは別のカードで再試行できます。フォームはメッセージの上に再び開くことはありません。購入者が Pay をクリックします。

Niubiz から応答がない場合: Niubiz が明確な回答を返さない場合（タイムアウト、サーバーエラー、読み取れない応答）、注文には On Hold Status が設定され、完了ページには We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. と表示されます。Niubiz が注文と一致しない決済を承認した場合、完了ページには Your payment was received and is being reviewed by the store. We will contact you if anything else is needed. と表示されます。

リクエストが拒否された場合: Niubiz がリクエスト自体を拒否した場合（認証情報の不正や購入番号の重複など）、注文はステータスなしのままとなり、メモが追加されて、購入者には Niubiz could not process the payment and your card was not charged. と表示されます。その時点で Niubiz API に接続できない場合、購入者には We could not connect to Niubiz and your card was not charged. Please try again in a few minutes. と表示されます。

注文が変更された場合: フォームが送信された時点で注文合計金額がセッションと一致しなくなった場合、決済は承認されず、購入者には Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again. と表示されます。

セッションの有効期限切れ: Niubiz の決済セッションは最長 20 分間有効です。セッションが既に使用されている場合、残りが 5 分未満の場合、別のモードまたは加盟店 ID に属する場合、または注文合計金額が変更された場合、決済ページは新しいセッションを作成します。

決済を試行するたびに、新しい購入番号が付与されます。購入番号は注文番号に 3 桁の試行番号を付けたもので、Niubiz は承認ごとに一意の購入番号を要求するためです。OpenCart 3 では、Confirm Order のステップが表示されるたびに新しい注文が作成されます。OpenCart 4 では、チェックアウトの注文は 1 件にまとめられて更新されるため、カードが拒否された後も、購入者は同じ注文に新しい購入番号で支払います。既に支払い済みのカートが再び決済されることはありません。その場合、購入者は代わりに支払い済み注文の完了ページに案内されます。

OpenCart 4 では、成功ページが表示されるまで注文はチェックアウトに保持されます。その間に決済されないまま注文が閉じられた場合（例：お客様がキャンセルした場合）、購入者は Your previous order was cancelled or its payment failed. Please confirm the order again. と表示されてチェックアウトに戻り、次の Confirm Order で新しい注文の支払いが行われます。その注文に既にステータスが設定されていて、カートにその後別の商品や数量が追加されている場合、メッセージは Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. となります。OpenCart 4 では、購入者をチェックアウトに戻すメッセージ（例：The Niubiz payment could not be found. Please confirm your order again.）は、チェックアウトページの上部に表示されます。

決済ページ、Niubiz フォームの応答、ストアへの復帰も、ストアがメンテナンスモードの間に動作します。OpenCart 3 では支払い拡張機能のリクエストが通過できます。OpenCart 4 では、拡張機能がそのためのスタートアップアクションを追加します。

この拡張機能は、一回限りのカード決済のみに対応しています。OpenCart からの返金やキャンセル、カードの保存、サブスクリプションや定期決済、分割払い（cuotas）の選択、PagoEfectivo、Yape などのその他のウォレットや QR 決済には対応していません。応答が失われたために保留にされた注文は、自動的には再確認されません。

注文

注文ステータス

ステータスなし（欠落注文）: 購入者は決済ページにいて、まだ支払っていないか、カードが拒否されたか、リクエストが拒否されています。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。拒否や却下は注文のメモに追加されます。

OpenCart 4 では、チェックアウトの未払い注文に Voided ステータスが設定されることがあります。これは、購入者が Confirm Order のステップに戻ったときに OpenCart 4 が設定するものです。拡張機能はそのような注文をステータスなしの注文として扱い、後の決済でも確認されます。

Order Status After Payment（既定値 Processing）: Niubiz が決済を承認し、応答が注文と一致しました。メモには、環境、トランザクション ID、承認コード、購入番号、カードブランドとマスクされたカード番号が表示されます。

On Hold Status（既定値 Pending）、承認済みだが一致しない: Niubiz が、購入番号、金額、通貨が注文と異なる決済、または応答に金額や通貨が含まれていない決済を承認しました。注文は支払い済みとしてマークされません。メモには相違点が一覧表示されます。Niubiz コンソールでトランザクションを確認してください。

On Hold Status（既定値 Pending）、明確な回答なし: Niubiz が明確な回答をしなかったため、カードに請求された可能性があります。メモには購入番号が記載されます。Niubiz コンソールで検索してください。トランザクションが承認されており正しければ、注文を支払い済みのステータスに設定します。そうでなければキャンセルします。

既に支払い済みのカートに対して 2 回目の決済の応答があった場合、2 つ目のステータスは設定されません。支払い済み注文のメモには購入番号、トランザクション ID、金額が記載されるため、必要に応じて Niubiz コンソールで確認し、返金または取り消しができます。

メモは、購入者には表示されない注文の History の項目です。

VibeFox Niubiz Payment タブ

Sales > Orders で、Niubiz で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Niubiz Payment タブには、購入番号、環境（サンドボックスまたは本番）、Niubiz answer、トランザクション ID、承認コード、カード、金額（および Niubiz が承認した金額）、見つかった問題、試行回数、そして注文の Niubiz notes が表示されます。保留ステータスの注文については、このタブが Niubiz コンソールで購入番号を確認するよう促します。このタブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

返金とキャンセルは OpenCart からはできません。Niubiz コンソールでトランザクションを返金または取り消しし、注文ステータスを手動で更新してください。Sales > Returns での商品の返品では、Niubiz を通じて返金は行われません。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox Niubiz Payment は、Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit の最初のブロックで、設定の上部にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-payment-niubiz の行と、ご自身の vibefox.net アカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれています）。

キーが受け付けられない場合、ブロックは理由を表示します。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。このドメインは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで Niubiz は購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合、支払い方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。すでに開始された決済は引き続き確認されます。

ライセンスが期限切れになっても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Niubiz が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの加盟店 ID、API ユーザー、API パスワードが入力されていること（サンドボックスモードでは sandbox のフィールド、それ以外では本番のフィールド）、そして購入者が PEN または USD で支払っていることを確認してください。認証情報や通貨が正しくない場合、設定ページに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

決済は完了したが、注文がステータスなしのままになっている: Niubiz はこの決済フォームに Webhook を持たないため、注文は承認への応答からのみステータスを受け取ります。購入者がフォームを完了していなければ、何も支払われていません。そうでない場合は、拡張機能のページの Log フィールドを確認し、Niubiz コンソールで購入番号を検索してください。Niubiz が応答したがステータスを設定できなかった場合、購入者には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. と表示され、購入者が決済ページを開くか、カートを再確認すると、拡張機能はステータスの設定を再試行します。

購入者に We could not connect to Niubiz と表示される: アクセストークンを取得できませんでした。現在のモードの API ユーザーと API パスワード、およびサーバーから Niubiz API に接続できるかを確認してください。詳細は Debug log をオンにして確認できます。

購入者に We could not start the Niubiz payment と表示される: Niubiz が決済セッションを作成しませんでした。現在のモードの加盟店 ID とログを確認してください。

購入者に This payment attempt was already processed と表示される: 同じフォームが 2 回送信されました。購入者は決済ページで決済をやり直します。カードが二重に請求されることはありません。

購入者に This order is already being paid と表示される: 別のリクエストが、その瞬間に同じカートを承認しています。購入者はしばらく待ち、再試行する前にメールを確認します。

メモに Niubiz reported a duplicate authorization と表示される: Niubiz は既にこの購入番号を把握しています。Niubiz コンソールで確認してください。購入者は新しい購入番号で再試行できます。

注文が保留ステータスになっている: VibeFox Niubiz Payment タブのメモを確認してください。Niubiz が明確な回答をしなかったか、注文と一致しない決済を承認しました。Niubiz コンソールで購入番号を検索し、注文を支払い済みのステータスに設定するか、キャンセルしてください。

設定の保存時にエラーが出る: 加盟店 ID は数字のみでなければならず、ロゴ URL は有効な https:// アドレスでなければならず、タイトルは空であったり 128 文字を超えたりしてはなりません。以前の値が維持されます。

開発者向け：Niubiz が加盟店固有の不正検知フィールド（MDD）の送信を求める場合、別の拡張機能が OpenCart のイベント niubiz_p_merchant_define_data を使ってそれを追加できます。決済セッションとともに送信されるカード所有者のデータは、イベント niubiz_p_cardholder_data で変更できます。

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox Niubiz Payment の横にある Uninstall（赤色の − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、イベントとスタートアップアクションも削除されます。このスタートアップアクションは、メンテナンスモード中も決済ページ、Niubiz フォームの応答、ストアへの復帰を通過させます）。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、サンドボックスモード、認証情報、ロゴ、ログ設定）とログが削除されます。オフの場合は、後で再インストールする際のために保持されます。Niubiz の決済試行（購入番号、環境、トランザクション ID）は、決済履歴として常に保持されます。既存の注文は決済メモを保持します。

OpenCart 4 では、拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧にある VibeFox Niubiz Payment の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いごみ箱のボタン）をクリックします。

Niubiz は各所有者の商標です。この拡張機能は Niubiz と提携しておらず、Niubiz による推奨もされていません。