VibeFox Vindi for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。

ショップ通貨: ブラジルレアル（BRL）。Vindi は BRL でのみ請求するため、それ以外の通貨のカートでは決済方法が非表示になります。

Vindi アカウント: Vindi アカウントの API キーが必要です。Vindi サンドボックスは、独自のキーを持つ別の Vindi テストアカウントです。boleto、PIX、BolePix を提供する場合は、Vindi アカウントでも有効にしておく必要があります。

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

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Vindi Gateway を探して Configure をクリックします。

3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーの項を参照）。

4. Sandbox API key を貼り付けます。準備ができたら Live API key も貼り付けます。Offered methods を選択します。

5. 設定に表示されている Webhook URL を、Vindi にコピーします（「設定」を参照）。

6. Enable / Disable を有効にして Save をクリックします。サンドボックスモードで決済をテストした後、Sandbox mode を無効にして実際の決済を受け付けます。

インストール時に、モジュールは 2 つの注文ステータスを作成します：Awaiting Vindi payment と Vindi payment on hold。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できます。そこで本モジュールが BRL に対して許可されている必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Vindi Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部には、ショップ通貨が BRL でない場合、または現在のモードの API キーが空の場合に警告が表示されます。どちらの場合も、決済方法はチェックアウトに表示されません。保存時にはキーの前後の空白が取り除かれます。決済方法が 1 つも選択されていない場合は、クレジットカードが選択され、ページには Choose at least one payment method — credit card was selected. と表示されます。空の Title は保存されず、ページには Enter a title for the payment method. と表示されます。

Vindi

Enable / Disable: Enable Vindi payments は、決済方法のオン／オフを切り替えます。デフォルト：オフ。

Title: チェックアウトで表示される決済方法の名称です。注文に保存される決済方法の名称にもなります。デフォルト：Vindi。必須。

Description: チェックアウトで決済方法の下に表示されるテキストです。デフォルト：Pay by credit card on the secure Vindi page, or by boleto / PIX.

API キー

キーは Vindi のダッシュボードで Settings > API keys から作成します。本番環境は app.vindi.com.br、サンドボックスは sandbox-app.vindi.com.br です。本番環境とサンドボックスではホストとキーが別々です。各決済は請求書を作成した環境を記録するため、確認、キャンセル、返金は常にその環境で行われます。

Sandbox mode: sandbox-app.vindi.com.br とサンドボックス用 API キーを使用して、Vindi サンドボックスで新しい決済を作成します。チェックアウトでは、購入者に TEST MODE という表示が見えます：Vindi sandbox: no real charges. デフォルト：オン。実際の決済を受け付けるには、オフにします。

Live API key: 本番の Vindi アカウントの秘密鍵です。Vindi API にのみ送信されます。

Sandbox API key: Vindi サンドボックスアカウントの秘密鍵です。

保存済みのキーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ、新しい値を入力してください。

Clear saved keys: キーにチェックを入れ、Save をクリックして削除します。フィールドが空の場合は、保存済みの値が保持されます。

決済方法

Offered methods: 購入者が選択できる決済方法です。デフォルト：クレジットカード。これらの方法は、Vindi アカウントでも有効にしておく必要があります。

Credit card: 購入者は Vindi の請求書ページで支払います。

Boleto: boleto はすぐに発行され、注文は Awaiting Vindi payment のまま残ります。

PIX: PIX の QR コードとコピー＆ペースト用コードがすぐに発行され、注文は Awaiting Vindi payment のまま残ります。

BolePix（boleto + PIX）: PIX でも支払える boleto で、boleto や PIX と同様にすぐに発行されます。

boleto、PIX、BolePix には、チェックアウトで入力を求められる購入者の CPF または CNPJ が必要です。

決済通知（ウェブフック）

ウェブフックは、請求書が支払い済み、キャンセル、拒否、または返金されたことをショップに通知します。このセクションの Webhook URL フィールドに URL が表示されます。フレンドリー URL が有効な場合は、https://your-shop/module/wcp_vindi_gateway/webhook?token=... のような形式になり、モジュールが生成した秘密のトークンが含まれます。設定に表示されているとおりに、そのままコピーしてください。Vindi で Settings > Webhooks に移動し、本番アカウントとサンドボックスアカウントの両方でこの URL を追加して、次のイベントを選択します：

bill_paid: 請求書が支払われました。

bill_canceled: 請求書がキャンセルされました。

charge_rejected: 決済の試行が拒否されました。

charge_refunded: 決済が返金されました（例：Vindi ダッシュボードでの返金）。

Vindi は通知に署名しないため、トークンが欠けているか誤っているリクエストは拒否されます。また、各通知は、注文が変更される前に、モジュールが Vindi API を通じて請求書を再度読み取るだけです。ウェブフックがない場合、カード決済は、購入者が同じカートで注文をやり直したときにのみ検出されます（支払い済みの請求書が見つかり、注文が作成されます）。boleto や PIX の決済は、購入者が注文確認ページを再度開いたときに検出されます。

詳細設定

Debug log: API 呼び出しと通知を、モジュールフォルダー内の logs/wc_vdi_debug.log.php に記録します。このファイルはウェブから開くことはできません。このオプションがオフでも、エラーと警告は常に記録されます。キー、ウェブフックのトークン、顧客データは記録されません。デフォルト：オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールすると、設定、ウェブフックのトークン、ログが削除されます。注文と、注文の Vindi 請求書の参照情報は保持されます。デフォルト：オフ。

チェックアウト

購入者は決済方法を選択します（デフォルトは Vindi）。複数の方法が提供されている場合、支払いボックスに Pay with と、クレジットカード、boleto、PIX、BolePix の選択肢が表示されます。boleto、PIX、または BolePix が提供されている場合、ボックスには CPF or CNPJ フィールドも表示されます。クレジットカードが提供されていない場合はこのフィールドが必須で、それ以外の場合は Required for boleto and PIX. と表示されます。請求先住所の Identification number または VAT 番号に有効な CPF または CNPJ が含まれている場合、このフィールドには自動的にその値が入力されます。番号は検証番号によって確認されます。不足している項目がある場合、購入者には Please choose how you want to pay with Vindi.、Please enter a valid CPF or CNPJ.、または Please enter your CPF or CNPJ — it is required for boleto and PIX. と表示されます。

購入者が注文を確定すると、モジュールは請求先住所から、このカートの Vindi 顧客を作成し、カートの合計金額で、1 回払いの Vindi 請求書を作成します。Vindi 上では、請求書は Order # とカート番号の形式で登録されます。

クレジットカード: 購入者は Vindi の請求書ページに移動し、そこで支払います。この時点ではまだ注文は存在しません。Vindi には請求書用の戻り URL がないため、購入者はショップに自動的に戻されません。注文は、Vindi がウェブフックによって決済を確認すると作成されます。購入者が同じカートで注文をやり直した場合、保留中の請求書が再度提示されます。すでに支払い済みの場合は、注文がすぐに作成されます。

boleto、PIX、BolePix: 請求書はすぐに発行され、注文は Awaiting Vindi payment のステータスで作成されて、購入者は注文確認ページに移動します。そのページ、および購入者のマイアカウントの注文詳細には Payment セクションが表示され、PIX の QR コード、Copy code ボタン付きの PIX コピー＆ペースト用コードとその有効期限、そして Open boleto ボタンが表示されます。注文確認メールには PIX コードと boleto のリンクが含まれます。Vindi が boleto または PIX のデータを返さない場合、請求書はキャンセルされ、購入者にはエラーが表示されます。

注文は、Vindi が確認した後にのみ支払い済みとしてマークされます。モジュールは Vindi API から請求書を読み取り、通貨、請求書がカートに属していること（カートコードと Vindi 顧客）、支払い金額が注文合計と等しいことを確認します。注文確認ページは、保留中の注文を API で再確認します（最大 15 秒ごと）。支払いが受領されると、Your payment with Vindi has been received. と表示されます。請求書が Vindi で審査中の間は、We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. と表示されます。キャンセルされた注文の場合は、This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid. と表示されます。

同じカートに対する新しい決済試行では、決済方法、金額、環境が同じであれば、保留中の Vindi 請求書が再利用されます。それ以外の場合は、新しい請求書を作成する前に、以前の請求書が Vindi でキャンセルされるため、購入者が同じカートに二重に支払うことはできません。その間に以前の請求書が支払われていた場合は、注文が作成され、新しい請求書は発行されません。

Vindi が決済を開始できない場合、購入者はチェックアウトページに留まり、簡単なメッセージが表示されます。たとえば、CPF / CNPJ、請求先住所（boleto の場合は番地、郵便番号、市区町村、都道府県が必須）、メールアドレス、電話番号を確認するよう求めるメッセージや、Vindi が一時的に利用できないことを知らせるメッセージです。技術的な理由はログに記録されます。

ウェブフックは、ショップがメンテナンスモードの間も動作し、ショップの国別制限によってブロックされることはありません。

本モジュールが扱うのは、1 回払いの単発決済だけです。定期購入や継続課金、保存済みカード、分割払い、ショップのサイト上のカードフォームには対応していません。カードは常に Vindi のページで入力されます。

注文と返金

注文ステータス

No order yet: カード決済が開始されましたが、Vindi はまだ確認していません。カートだけが存在します。

Awaiting Vindi payment: boleto、PIX、BolePix の決済が保留中です（メモ Awaiting ... payment at Vindi.）。Vindi が請求書の支払い済みを報告すると、注文は Payment accepted に移行します。

Payment accepted: 決済が確認されました。決済は Vindi の請求書 ID をトランザクション ID として記録され、メモには Vindi の請求書、金額、環境が表示されます。

Vindi payment on hold: Vindi の請求書が審査中であるか、支払い済みの請求書が注文と一致しない（通貨、金額、カートコード、Vindi 顧客のいずれか）か、または注文がキャンセルされた後に請求書が支払われました。メモにその理由が記載され、支払い済みの金額が注文に記録されます。注文と在庫を確認してから、注文を完了するか、決済を返金してください。

Payment error: Vindi が、保留中の注文の決済試行を拒否しました。理由がある場合、メモには加盟店契約会社（アクワイアラー）からの理由が表示されます。購入者は同じ請求書を引き続き支払うことができ、その後の決済によって注文は Payment accepted に移行します。

Canceled: 保留中の注文の請求書が Vindi でキャンセルされました。ショップで注文をキャンセルすると、保留中の Vindi 請求書もキャンセルされるため、支払いできなくなります。それができない場合は、メモに Vindi ダッシュボードで請求書をキャンセルするよう指示が表示されます。

Refunded: モジュールを通じて、決済が全額返金されました。

すでに支払い済みの注文に対して 2 つ目の請求書が支払われた場合、注文は変更されません。メモには、Vindi で 1 件の決済を返金するよう指示が表示されます。

Vindi 決済ブロック

注文画面には Vindi payment ブロックが表示され、Vindi の請求書と請求、環境（サンドボックス決済には Sandbox バッジ付き）、決済方法、ステータス、支払い済み金額と返金済み金額、返金履歴、すべての Bills of this cart、そして注文の Vindi notes が含まれます。

返金

Vindi payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Vindi をクリックします。確認メッセージ Refund this amount through Vindi? This cannot be undone. で承認します。クレジットカードおよび PIX 決済の全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセスは必要ありません。返金は Vindi が実際に請求した金額までに制限されるため、金額の不一致が生じた後は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。返金は決済の環境（本番またはサンドボックス）で送信されるため、その環境の API キーが設定されている必要があります。全額返金を行うと、Vindi の請求書もキャンセルされ、注文は Refunded に設定されます。一部返金ではステータスは変わりません。返金が成功すると、Vindi の請求と、そのステータスとともに、返金履歴とメモに追加されます。Vindi またはアクワイアラーが返金を拒否した場合は、ブロックにエラーが表示され、返金は記録されません。返金は、Vindi が請求書の支払い済みを報告した後に利用できます。

Vindi では boleto の決済を返金できません。ブロックには Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually. と表示されます。

モジュールは貸方票（credit slip）を作成しません。注文画面の標準の PrestaShop の返金ボタンでは、Vindi を通じて返金は行われません。Vindi ダッシュボードで行われた返金は、charge_refunded ウェブフックによって届き、メモに追加されます。注文ステータスは自動的には変更されません。必要に応じて、PrestaShop で手動返金として記録してください。

ライセンスキー

本モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Vindi Gateway は、Modules > Module Manager > VibeFox Vindi Gateway > Configure ページの最初のブロックで、設定の上に表示されます。キーを License key に入力して Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（例：ライセンスの有効期限日とお使いのドメイン）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-vindi の行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで購入者に Vindi は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントはバックオフィスにログインしていることを認識しないため、ログイン中の管理者にも決済方法は表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに作成された請求書は、Vindi のウェブフックによって引き続き確認され、返金も機能します。

ライセンスの有効期限が切れてもモジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Vindi が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、カートの通貨が BRL であること、Offered methods で少なくとも 1 つの方法が選択されていること、そして現在のモードに API キーがあることを確認してください。サンドボックスモードでは Sandbox API key、本番モードでは Live API key です。キーがない場合や通貨が BRL でない場合、設定ページに警告が表示されます。Payment > Preferences で、モジュールが BRL、購入者の国、購入者のグループに対して許可されていることを確認してください。

決済は完了したのに注文が作成されない、または注文が Awaiting Vindi payment のまま: ウェブフックが機能していません。使用しているアカウント（本番またはサンドボックス）の Vindi にウェブフックが存在すること、その URL が設定に表示されているもの（トークンを含む）と完全に一致すること、そして 4 つのイベントすべてが選択されていることを確認してください。

ウェブフックが Forbidden を返す: URL のトークンが欠けているか、誤っています。設定から URL を再度コピーしてください。

ウェブフックが Verification failed, retry later を返す: Vindi API から請求書を読み取れなかった（たとえば、その環境の API キーが削除された）、同じ時刻に別のリクエストによってカートが更新されていた、または注文を作成できなかった（たとえば、モジュールが無効になっている）。Vindi は通知を再送します。ログに理由が表示されます。

ブラウザでウェブフック URL に Method not allowed と表示される: これは正常です。この URL は Vindi からのリクエストのみを受け付けます。

購入者に This payment method is temporarily unavailable と表示される: Vindi が API キーを拒否しました。現在のモードのキーを確認してください。

注文の確定時に購入者にエラーが表示される: モジュールのページにある Log フィールドを確認してください。Debug log がオフの場合でも、エラーは記録されます。boleto の場合、請求先住所には番地、郵便番号、市区町村、都道府県が必要です。

注文が Vindi payment on hold になっている: Vindi payment ブロックのメモを確認し（注文ステータスを参照）、注文を完了するか、決済を返金してください。

本番に切り替えた後に古いサンドボックスの注文がある: 各決済は、その請求書の環境を保持します。サンドボックスキーが設定に残っている限り、サンドボックスの注文の確認、キャンセル、返金は引き続きサンドボックスキーを使用します。

返金に失敗する: メッセージを確認してください。boleto の決済は Vindi を通じて返金できず、決済の環境の API キーが設定されている必要があります。

アンインストール

Modules > Module Manager に移動し、VibeFox Vindi Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、設定、ウェブフックのトークン、ログが削除されます。オフの場合、後で再インストールできるようにすべての設定が保持されます。注文の Vindi 請求書と返金、および注文ステータス Awaiting Vindi payment と Vindi payment on hold は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、決済のメモとトランザクション ID を保持します。

Vindi は、それぞれの所有者の商標です。本モジュールは Vindi と提携しておらず、Vindi による推奨も受けていません。