VibeFox Vindi for WooCommerce — ヘルプ
要件
WordPress: 6.0 以降。
WooCommerce: 8.0 以降。インストールされ、有効になっている必要があります。WooCommerce がなければ、プラグインは有効化できません。
PHP: 8.0 以降。
ストア通貨: ブラジルレアル（BRL）。Vindi は BRL でのみ請求するため、それ以外の通貨では決済方法が表示されません。
Vindi アカウント: Vindi アカウントの API キーが必要です。Vindi サンドボックスは、独自のキーを持つ別のテスト用アカウントです。boleto、PIX、BolePix を提供する場合は、Vindi アカウントでそれらも有効にしておく必要があります。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックし、続けて Activate をクリックします。FTP で wcp_vindi_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. 設定を開きます。WooCommerce > Settings > Payments > Vindi > Manage、またはプラグインの一覧ページでプラグイン名の下にある Settings をクリックします。
3. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
4. Sandbox API key を貼り付けます。準備ができたら Live API key も貼り付けます。Offered methods を選択します。
5. 設定画面のウェブフック URL を Vindi にコピーします（「設定」を参照）。
6. Enable / Disable をオンにして保存します。サンドボックスモードで決済をテストしてから、Sandbox mode のチェックを外すと、実際の決済を受け付けられます。
設定
すべての設定は 1 つのページにまとまっています：WooCommerce > Settings > Payments > Vindi。入力欄の上部には、ストア通貨が BRL でない場合、または現在のモードの API キーが空の場合に警告が表示されます。どちらの場合も、チェックアウトに決済方法は表示されません。決済方法の一覧では、現在のモードに API キーが設定されるまで、Vindi に設定が必要であることが示されます。保存時にはキーの前後の空白が削除されます。決済方法が 1 つも選択されていない場合、クレジットカードが自動的に選択され、ページには Choose at least one payment method — credit card was selected. と表示されます。
一般
Enable / Disable: Enable Vindi payments で決済方法のオン・オフを切り替えます。既定値: off。
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: Create new payments in the Vindi sandbox を有効にすると、サンドボックスの API キーを使って sandbox-app.vindi.com.br で決済が行われます。購入者はチェックアウトで TEST MODE の表示を確認します：Vindi sandbox: no real charges. 既定値: on。実際の決済を受け付けるには、チェックを外します。
Live API key: 本番の Vindi アカウントの秘密キーです。Vindi API にのみ送信されます。
Sandbox API key: Vindi サンドボックスアカウントの秘密キーです。
決済方法
Offered methods: 購入者が選択できる決済方法です。既定値: credit card。これらの方法は、Vindi アカウントでも有効にしておく必要があります。
決済通知（ウェブフック）
ウェブフックは、請求書が支払い済み、キャンセル済み、または返金済みになったことをストアに通知します。この設定セクションにはウェブフック URL が表示されます。URL の形式は https://your-site/wc-api/webhook_wc_vindi/?token=... で、プラグインが作成した秘密のトークンを含みます。設定に表示されているとおりに正確にコピーしてください。Vindi で本番アカウントとサンドボックスアカウントの両方について Settings > Webhooks に進み、この URL を追加して、次のイベントを選択します：
トークンが欠けている、または誤っているリクエストは拒否されます。各通知によって行われるのは、注文が変更される前に、プラグインが Vindi API を通じて請求書を読み直すことだけです。ウェブフックがない場合、カード、boleto、PIX の決済は、購入者が注文受付ページを開いたときにのみ確認されます。
詳細設定
Debug log: Log API calls and notifications を有効にすると、詳細が WooCommerce > Status > Logs に、ソース wcp_vindi_gateway として書き込まれます。エラーと警告は、この設定がオフでも常に記録されます。キーと購入者データが記録されることはありません。既定値: off。
Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted。既定値: off。
チェックアウト
購入者は決済方法を選択します（既定では Vindi）。複数の方法が提供される場合、決済ボックスに Pay with と、クレジットカード、boleto、PIX、BolePix からの選択肢が表示されます。boleto、PIX、BolePix が提供される場合、ボックスには CPF or CNPJ フィールドも表示されます。これらの方法だけが提供される場合は必須で、それ以外の場合は Required for boleto and PIX. と表示されます。番号は検証番号で確認されます。クラシックチェックアウトでは、Brazilian Market on WooCommerce が有効な場合、そのプラグインがすでに CPF / CNPJ を求めるため、このフィールドは表示されません。その場合は、そのプラグインの 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 請求書を作成します。
Credit card: 購入者は Vindi の請求書ページに移動し、そこで支払います。Vindi には請求書用の戻り URL がないため、購入者が自動的にストアへ戻ることはありません。注文は、ウェブフックによって、または購入者が注文受付ページを開いたときに確認されます。支払いが完了するまで、そのページと My account の注文には Your payment has not been completed yet. と Pay at Vindi ボタンが表示されます。
Boleto、PIX、BolePix: 請求書はすぐに発行され、注文は保留中に設定され、購入者は注文受付ページに移動します。そこと My account > Orders には、Payment セクションに PIX の QR コード、Copy code ボタン付きの PIX のコピー&ペースト用コードとその有効期限、そして Open boleto ボタンが表示されます。購入者の保留中注文のメールと請求書のメールには、PIX のコードと boleto のリンクが含まれます。
注文が支払い済みになるのは、Vindi が確認した後だけです。プラグインは Vindi API から請求書を読み取り、それが注文に属していること（注文コードと Vindi 顧客）、および支払われた金額が注文合計と等しいことを確認します。
購入者は Pay for order ページから未払いの注文を再度支払うことができます。決済方法、金額、環境が同じであれば、保留中の Vindi 請求書が再利用されます。そうでない場合は、新しい請求書を作成する前に Vindi で既存の請求書がキャンセルされるため、購入者が同じ注文を二重に支払うことはできません。前の請求書がその間に支払われていた場合、注文は支払い済みになり、新しい請求書は作成されません。
Vindi が決済を開始できない場合、購入者には短いメッセージが表示されます。たとえば、CPF / CNPJ、請求先住所、メールアドレス、電話番号を確認するよう求めるメッセージや、Vindi が一時的に利用できないことを知らせるメッセージです。同じ注文がその時点で別のリクエストによって処理されている場合、購入者は少し待ってから再度試すよう求められます。
この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文保存（HPOS）に対応しています。
本プラグインが扱うのは、1 回払いの単発決済だけです。定期購入や継続課金、保存済みカード、分割払い、貴店のサイト上のカードフォームには対応していません。カードは常に Vindi のページで入力します。
注文と返金
注文ステータス
Pending payment: カード決済が開始されましたが、Vindi はまだ確認していません。
On hold: boleto、PIX、BolePix の決済が待機中です（メモ Awaiting ... payment at Vindi.）。または Vindi の請求書が審査中です。
Processing or Completed: 決済が確認されました。ステータスは WooCommerce の標準的な方法で設定されます。処理中、またはダウンロード可能なバーチャル商品のみの注文の場合は完了です。注文メモには、Vindi の請求書、金額、環境が表示されます。取引 ID は Vindi の請求書 ID です。
On hold after payment: 支払われた請求書が注文と一致しない（金額、注文コード、Vindi 顧客のいずれか）、または注文がキャンセルされた後に請求書が支払われました。注文メモに理由が記載されています。注文と在庫を確認してから、注文を完了するか、決済を返金してください。
Failed: Vindi が決済の試行を拒否しました。メモには、利用可能な場合、カード会社（アクワイアラ）からの理由が表示されます。購入者は同じ請求書を引き続き支払うことができ、後からの決済で注文が完了します。
Cancelled: 請求書が Vindi でキャンセルされたか、注文があなた、購入者、または WooCommerce の在庫保持タイムアウトによってキャンセルされました。ストアで注文がキャンセルされると、保留中の Vindi 請求書もキャンセルされるため、支払うことはできなくなります。それができない場合は、メモで Vindi のダッシュボードから請求書をキャンセルするよう案内されます。在庫保持タイムアウトによって注文がキャンセルされる前に請求書が確認され、その間に支払われていた場合は、代わりに注文が支払い済みになります。
すでに支払い済みの注文に対して 2 つ目の請求書が支払われた場合、注文は再び変更されません。メモで、Vindi において 1 件の決済を返金するよう案内されます。
返金
注文を開き、Refund をクリックして金額を入力し、Refund via Vindi をクリックします。カードおよび PIX の決済について、全額返金と一部返金がサポートされています。全額返金は、Vindi の請求書もキャンセルします。返金は決済の環境（本番またはサンドボックス）で送信されるため、その環境の API キーが設定されている必要があります。返金が成功すると、Vindi の請求内容と状態を含めて注文メモに追加されます。Vindi またはアクワイアラが返金を拒否した場合、WooCommerce はエラーを表示し、返金は記録されません。
Vindi は boleto 決済を返金できません。プラグインは Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually. と表示します。
Vindi のダッシュボードで行われた返金は charge_refunded ウェブフックで届き、注文メモに追加されます。WooCommerce の返金として自動的に記録されるわけではありません。必要であれば、Refund via Vindi を使わずに、WooCommerce で手動の返金を作成してください。
ライセンスキー
プラグインは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Vindi の上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ライセンスの有効期限日やお使いのドメインなど、ステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがないと、チェックアウトで購入者に Vindi は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された決済方法が引き続き見えるため、キーを購入する前にプラグインを設定してテストできます。プラグインの一覧ページと WooCommerce のページにはリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、返金も動作します。
ライセンスの期限が切れても、プラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに Vindi が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、ストア通貨が BRL であること、Offered methods で少なくとも 1 つの方法が選択されていること、現在のモードに API キーがあることを確認してください。サンドボックスモードでは Sandbox API key、本番モードでは Live API key です。キーがない場合や通貨が BRL でない場合、設定ページに警告が表示されます。
決済は完了したのに、注文が Pending payment または On hold のまま: ウェブフックが機能していません。Vindi で、使用しているアカウント（本番またはサンドボックス）にウェブフックがあること、その URL が設定に表示されたもの（トークンを含む）と完全に一致していること、4 つのイベントすべてが選択されていることを確認してください。購入者が注文受付ページを開いた場合にも、注文は確認されます。
ウェブフックが Forbidden を返す: URL のトークンが欠けているか、誤っています。設定から URL を再度コピーしてください。
ウェブフックが Verification failed, retry later または Order busy, retry later を返す: Vindi API から請求書を読み取れませんでした（たとえば、その環境の API キーが削除されている場合）。または、注文がちょうど別のリクエストによって更新されていました。Vindi は通知を再送します。
購入者に This payment method is temporarily unavailable と表示される: Vindi が API キーを拒否しました。現在のモードのキーを確認してください。
購入者が注文の確定時にエラーを見る: 注文メモ、または WooCommerce > Status > Logs のログ（ソース wcp_vindi_gateway）を開いてください。Debug log がオフでも、エラーは記録されます。boleto の場合、請求先住所には番地、郵便番号、市区町村、都道府県が必要です。
決済後に注文が On hold になる: 注文メモを確認してください。支払われた金額、注文コード、Vindi 顧客が注文と異なっていたか、注文がキャンセルされた後に決済が届きました。注文を完了するか、決済を返金してください。
本番に切り替えた後の古いサンドボックス注文: 各注文は、その請求書の環境を保持します。サンドボックスの注文の確認、キャンセル、返金は、設定にサンドボックスキーがある限り、そのキーを引き続き使用します。
返金が失敗する: メッセージを確認してください。boleto の決済は Vindi では返金できません。また、決済の環境の API キーが設定されている必要があります。
ライセンスブロックにエラーが表示される: ブロックのメッセージに従ってください。たとえば、キーがすでに別のドメインで使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変更された場合は、Check now をクリックして、新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作を続けます。
アンインストール
プラグインを無効化しても、すべてのデータは保持されます。削除するには、無効化してから Plugins ページで削除します。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、ウェブフックのトークン、その他の保存済みプラグインデータ、ログは、Delete data on uninstall がオンだった場合にのみ削除されます。そうでない場合は、後で再インストールするために保持されます。既存の注文は、決済メモ、取引 ID、Vindi のデータを保持します。
Vindi は、その所有者の商標です。本プラグインは Vindi と提携しておらず、Vindi による承認や推奨も受けていません。