VibeFox Flutterwave for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

WooCommerce: 7.0 以降。インストールして有効化しておく必要があります。WooCommerce がない場合、本プラグインは有効化できません。

PHP: 8.0 以降。古い PHP では本プラグインを有効化できません。

Flutterwave アカウント: Flutterwave ダッシュボードの Settings、API keys にある、貴店アカウントの秘密キーが必要です。テストモードは FLWSECK_TEST-…、本番モードは FLWSECK-… を使用します。使用するのは秘密キーのみで、公開キーや暗号化キーは不要です。また、任意の秘密ハッシュを使ってウェブフックを設定します（「設定」を参照）。

通貨: 請求は常に注文の通貨で行われます。プラグインは国や通貨を制限しません。貴店アカウントが通貨に対応していない場合、Flutterwave がエラーを表示します。

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin に移動し、プラグインの ZIP ファイルを選んで Install Now をクリックします。FTP で wcp_flutterwave_payment フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定画面 WooCommerce > Settings > Payments > Flutterwave > Manage を開くか、プラグインページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。

5. 秘密キーを入力し、Flutterwave ダッシュボードでウェブフックを設定して、同じ秘密ハッシュをプラグインに入力します（「設定」を参照）。

6. Enable/Disable を有効にしてテストモードで決済を試した後、Live mode にチェックを入れます。

設定

すべての設定は WooCommerce > Settings > Payments > Flutterwave の一つのページにあります。入力欄の上には Live mode: real payments are accepted. または Test mode: no real money is charged. が表示されます。現在のモードの秘密キーが空の場合、本番モードで本番キー欄にテストキー（FLWSECK_TEST-…）がある場合、テストモードでテストキー欄に本番キー（FLWSECK-…）がある場合は警告します。修正するまで、チェックアウトで支払い方法が非表示になります。ウェブフックの秘密ハッシュが未設定の場合も警告します。この場合ウェブフックは拒否され、購入者が貴店に戻ったときだけ決済が確認されます。支払い方法一覧では、現在のモードに秘密キーが設定されるまで Flutterwave に要設定の表示が付き、テストモードではテストモードのバッジが表示されます。

一般

Enable/Disable: Enable Flutterwave Payment で支払い方法を有効または無効にします。初期値: off。

Title: 購入者がチェックアウト時に見る支払い方法のタイトルです。初期値: Flutterwave。

Description: 購入者がチェックアウト時に見るテキストです。初期値: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API キー

Flutterwave ダッシュボードの Settings、API keys から秘密キーをコピーします。テストモードと本番モードは異なるキーを使用します。

Live mode: Accept real payments (uncheck for test mode)。テストモードはテスト用秘密キーを使用し、実際のお金は請求しません。本番モードは本番用秘密キーを使用します。初期値: off（テストモード）。

Test Secret Key: Flutterwave のテスト用秘密キー（FLWSECK_TEST-...）。

Live Secret Key: Flutterwave の本番用秘密キー（FLWSECK-...）。

ウェブフック

購入者が貴店に戻らなくても、ウェブフックが決済を確認します。Flutterwave ダッシュボードの Settings、Webhooks で、このセクションに表示される Webhook URL と任意の秘密ハッシュを、テストモードと本番モードの両方に入力します。URL の形式は https://your-site/wc-api/flw_p_webhook/ です。本プラグインは次のイベントに反応します。

その他のイベントは無視します。

Secret Hash: ウェブフックの秘密ハッシュです。Flutterwave ダッシュボードのウェブフック設定と同じ値にする必要があります。Flutterwave は各ウェブフックでこの値を送信します。有効な秘密ハッシュがないウェブフックは拒否されます。ウェブフックがない場合、購入者が貴店に戻ったときだけ決済が確認されます。

決済

Payment Options: Flutterwave ページに表示する支払い方法をカンマ区切りで入力します。例: card, banktransfer, ussd, mobilemoney。空欄の場合、アカウントで有効なすべての方法を表示します。保存時にリストが整理されます。

Autocomplete Orders: Automatically mark orders as completed after successful payment。有効にすると、支払い後に一度のステータス変更で注文を「処理中」ではなく「完了」にします。初期値: off。

詳細

Debug log: Log Flutterwave API events for debugging を WooCommerce > Status > Logs に記録します。ソースは wcp_flutterwave_payment です。エラーは常に記録します。キーや購入者データは一切記録しません。初期値: off。

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted。プラグインを無効化しても何も削除しません。注文に保存した決済データは常に保持します。初期値: off。

チェックアウト

購入者は支払い方法（初期値は Flutterwave）を選び、注文します。テストモードではチェックアウトに TEST MODE - no real payments will be processed. が表示されます。有効な請求先メールアドレスが必要です。プラグインは注文通貨で注文合計額の Flutterwave 決済を作成し、購入者のメールアドレス、電話番号、名前、貴店サイトの名前とロゴを含めて、購入者を Flutterwave チェックアウトページへ送ります。購入者はそこでアカウントで有効な方法（または Payment Options に記載した方法）で支払います。

支払い後、購入者は貴店に戻ります。注文を支払い済みにするのは、ウェブフック、または購入者が戻った際のサーバー側チェックで Flutterwave の確認を得てからです。銀行振込、USSD、モバイルマネーが保留中など、決済がまだ確認されていない場合、注文受付ページに Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. が表示されます。入金済みでも、支払額が注文と一致しない場合など、プラグインが確認のため注文を「保留中」にした場合、ページに Your payment was received and your order is being reviewed. We will contact you if anything is needed. が表示されます。

支払いが拒否されると、購入者はチェックアウト（または Pay for order ページ）に戻り、Your payment was declined. You can try again or choose another payment method. が表示されます。Flutterwave ページで購入者がキャンセルした場合、チェックアウトで作成した注文はキャンセルされ、手動作成の注文は未払いのままで、メッセージは Payment was cancelled. You can try again or choose another payment method. になります。支払いが完了しなかった場合、メッセージは The payment was not completed. You can try again or choose another payment method. です。

購入者は未払いの注文の支払いを再試行できます。各試行に固有の参照情報があり、古い決済リンクが後から支払われた場合も受け付けます。Flutterwave が決済を開始できない場合、購入者には短いメッセージ（例: Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.）が表示されます。

支払い方法はクラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。購入者向けテキストはフランス語に翻訳されています。

本プラグインは都度払いのみに対応しています。貴店サイト内の埋め込み型やモーダル型チェックアウト、保存済みカード、定期購入、分割送金、支払いプランには対応していません。ホストされた決済リンクは Flutterwave API から取り消せないため、注文の古いリンクでも支払いが可能です。

注文と返金

注文ステータス

Pending payment: 購入者は Flutterwave に移動しましたが、まだ支払っていないか、Flutterwave 側で支払いが保留中です。

Processing or Completed: 決済が確認されました。Autocomplete Orders が有効な場合は「完了」を使用します（仮想かつダウンロード可能な商品のみの注文も、WooCommerce の標準動作で「完了」になります）。注文メモには金額、支払い方法、Flutterwave 参照情報、取引、モードが表示されます。注文の取引 ID は Flutterwave 参照情報です。

On hold after payment: 確認した金額または通貨が注文と一致しなかったか、注文のキャンセル後に入金されました。理由はメモに記載されます。注文を履行するか返金してください。返金済みまたはキャンセル済みの注文が、再送されたウェブフックで再開されることはありません。

Failed: Flutterwave が、支払い待ち注文の最新の決済試行を失敗またはキャンセルとして報告しました。理由はメモに表示されます。

Cancelled: 購入者がチェックアウトで注文後に Flutterwave ページでキャンセルしたか、貴店が注文をキャンセルしたか、WooCommerce の在庫保持時間が切れて注文がキャンセルされました。

支払い済みの注文に二度目の支払いが届いても、注文は変更しません。Flutterwave ダッシュボードで重複分を返金するようメモが追加されます。

返金

注文を開いて Refund をクリックし、金額を入力して Refund via Flutterwave をクリックします。全額返金と一部返金に対応しています。返金は決済時のモード（テストまたは本番）の秘密キーで送信するため、そのキーの設定が必要です。Flutterwave が返金を拒否すると、WooCommerce にエラーが表示され、返金は記録されません。成功した返金は、返金 ID とステータス（完了、または Flutterwave が報告するステータスで開始済み）とともに注文メモに追加されます。

Flutterwave ダッシュボードで行った返金は WooCommerce に同期されません。必要に応じて、Refund via Flutterwave を使わずに WooCommerce で手動返金を作成してください。

ライセンスキー

本プラグインは vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > Flutterwave の上部にあります。License key にキーを貼り付け、Activate をクリックします。欄には、ライセンスの有効期限や貴店のドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを取り除きます。Manage licenses and domains in your account リンクから vibefox.net アカウントを開けます。

一つのキーは一つのドメインで使用できます。サイトからキーを取り除いても、ドメイン枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、購入者のチェックアウトに Flutterwave は表示されません。それでも決済が開始されると、購入者には This payment method is not available. Please choose another one. が表示されます。ログイン済みのショップ管理者には (unlicensed — visible to admins only) の表示付きで引き続き支払い方法が見えるため、キー購入前に設定とテストができます。プラグインページと WooCommerce ページには通知が表示されます。既存の注文には影響せず、開始済みの決済は引き続き確認され、返金も機能します。

ライセンスの期限が切れてもプラグインは動作し続けますが、更新とサポートには更新手続きが必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Flutterwave が表示されない: ライセンスが有効で、Enable/Disable がオンになっており、現在のモードの秘密キーが入力されてモードと一致しているか確認してください。テストモードはテストキー（FLWSECK_TEST-…）、本番モードは本番キー（FLWSECK-…）です。一致しない場合は設定ページに警告が表示されます。

支払いは済んだが注文が Pending payment のまま: ウェブフックが動作していません。Flutterwave ダッシュボードで、使用モード（テストまたは本番）のウェブフック URL が設定に表示されたものと完全に一致し、秘密ハッシュがプラグインの Secret Hash と同じか確認してください。保留中の銀行振込、USSD、モバイルマネーは、Flutterwave の確認まで保留のままです。Debug log を有効にし、WooCommerce > Status > Logs でソース wcp_flutterwave_payment を確認してください。

ウェブフックが Invalid hash または Secret hash not configured を返す: Flutterwave ダッシュボードとプラグインで秘密ハッシュが異なるか、プラグインに未設定です。両方に同じ値を入力してください。

ウェブフックが Verification failed または Busy, retry later を返す: 決済確認のため Flutterwave に接続できなかったか、取引がまだ表示されないか、別のリクエストが注文を更新中でした。Flutterwave はウェブフックを再試行します。

購入者に Payment gateway is not properly configured と表示される: 現在のモードの秘密キーがないか、別のモードのキーです。

購入者に We could not match this payment to an order と表示される: 戻りリンクに、このストアが作成していない参照情報が含まれています。購入者に請求済みの場合、Flutterwave ダッシュボードで決済を探してください。

Flutterwave のページにエラーが表示される: 貴店の Flutterwave アカウントが注文通貨または選択した支払い方法に対応していない可能性があります。

支払い後に注文が On hold になる: 注文メモを読んでください。確認した金額または通貨が注文と一致しなかったか、注文のキャンセル後に入金されました。注文を履行するか返金してください。

モードに関するメッセージで返金に失敗する: 決済時のテストまたは本番モードの秘密キーが設定されていません。入力して再試行してください。

ライセンス欄にエラーが表示される: 欄のメッセージに従ってください。たとえば別のドメインでキーを使用中の場合、vibefox.net アカウントで枠を解放し、Check now をクリックします。サイトのアドレスを変更した場合、Check now をクリックして新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合は、最後に確認したステータスで動作を続けます。

開発者向けに、プラグインのドキュメントにはフィルター flw_p_payment_request（Flutterwave に送信するデータ）、flw_p_currency_decimals（通貨の精度）、flw_p_icon（チェックアウトのアイコン）が記載されています。

アンインストール

プラグインを無効化してもすべてのデータを保持します。削除するには Plugins ページで無効化して削除します。このプラグインのライセンスキーとライセンスステータスは必ず削除されます。ゲートウェイ設定とログは Delete data on uninstall がオンだった場合のみ削除されます。それ以外は、後で再インストールするために保持します。注文に保存された Flutterwave データは常に保持します。既存の注文の決済メモと取引 ID も保持されます。

Flutterwave はその所有者の商標です。本プラグインは Flutterwave と提携しておらず、Flutterwave の承認も受けていません。