VibeFox Flutterwave for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは古い PHP バージョンではインストールできません。

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

通貨: カートは常にカートの通貨で請求されます。モジュール自体は国や通貨を制限しません。アカウントが通貨に対応していない場合、Flutterwave がエラーを表示します。通貨、国、顧客グループは Payment > Preferences で制限できます。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Flutterwave Payment を見つけて Configure をクリックします。

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

4. 秘密キーを入力し、Flutterwave ダッシュボードでウェブフックを設定して、同じ秘密ハッシュをモジュールに入力します（設定を参照）。

5. Enable/Disable をオンにして Save をクリックします。テストモードで決済を試してから、Live mode をオンにします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting Flutterwave payment と Flutterwave payment on hold を作成します。PrestaShop には、すべての通貨、国、顧客グループ向けの新しい支払いモジュールが追加されます。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Flutterwave Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。項目の上には、Live mode: real payments are accepted. または Test mode: no real money is charged. が表示されます。現在のモードの秘密キーが空の場合、本番キー欄に本番モードでテストキー（FLWSECK_TEST-…）が入っている場合、またはテストキー欄にテストモードで本番キー（FLWSECK-…）が入っている場合に警告が表示されます。この場合、問題が修正されるまで支払い方法はチェックアウトで非表示になります。ウェブフックの秘密ハッシュが設定されていない場合にも警告が表示されます。その場合、ウェブフックは拒否され、決済は購入者がショップに戻ったときにのみ確認されます。最初のセクションのタイトルには現在のモードが表示されます。TEST または LIVE です。

Flutterwave

Enable/Disable: Enable Flutterwave Payment で支払い方法をオンまたはオフにします。デフォルト: オフ。

Title: 購入者がチェックアウトで目にする支払い方法の名称です。注文に保存される支払い方法名にもなります。デフォルト: Flutterwave。必須。

Description: 購入者がチェックアウトで支払い方法の下に目にするテキストです。デフォルト: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API キー

Flutterwave ダッシュボードの Settings, API keys から秘密キーをコピーします（このセクションにはリンクがあります）。テストモードと本番モードでは、キーが異なります。

Live mode: 実際の決済を受け付けます。テストモードにするにはオフにします。テストモードではテスト用の秘密キーを使用し、実際の料金は請求されません。本番モードでは本番用の秘密キーを使用します。デフォルト: オフ（テストモード）。テストモードがオンの間、購入者は支払い方法の下に TEST MODE - no real payments will be processed. と表示されます。

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

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

保存されたキーと秘密ハッシュは、再び表示されることはありません。項目は空のままになり、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

Webhook

ウェブフックは、購入者がショップに戻らなくても決済を確認します。Flutterwave ダッシュボードの Settings, Webhooks で、このセクションの Webhook URL に表示された URL と、任意の秘密ハッシュを、テストモードと本番モードの両方に入力します。フレンドリー URL を使用している場合、URL は https://your-shop/module/wcp_flutterwave_payment/webhook のような形式になり、/en/ のような言語コードが付くこともあります。URL は設定画面に表示されたとおりにコピーしてください。モジュールは次のイベントに反応します:

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

Secret Hash: ウェブフックの秘密ハッシュです。Flutterwave ダッシュボードのウェブフック設定の値と一致している必要があります。Flutterwave はすべてのウェブフックにこの値を付けて送信し、テストモードと本番モードで同じ値を使用します。有効な秘密ハッシュがないウェブフックは拒否されます。ウェブフックがない場合、決済は購入者がショップに戻ったときにのみ確認されます。

Clear saved secrets: Test Secret Key、Live Secret Key、または Secret Hash にチェックを入れ、Save をクリックすると削除されます。空欄の場合は保存済みの値が保持されます。

支払い

Payment Options: Flutterwave ページに表示する支払い方法を、カンマ区切りで指定します（例: card, banktransfer, ussd, mobilemoney）。空欄にすると、アカウントで有効なすべての方法が表示されます。保存時にリストは整理されます（小文字に変換され、重複は削除されます）。

Autocomplete Orders: 支払い済みの注文は、Payment accepted ではなく Delivered ステータスになり、ステータス変更は 1 回だけ行われます。デフォルト: オフ。

詳細設定

Debug log: デバッグのために、Flutterwave API のイベントをモジュールフォルダー内の logs/flwv_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。キー、秘密ハッシュ、購入者データは記録されません。デフォルト: オフ。

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

Delete data on uninstall: モジュールをアンインストールすると、モジュールの設定とログを削除します。注文に保存された支払いデータは常に保持されます。デフォルト: オフ。

チェックアウト

支払いの段階で、購入者は支払い方法（デフォルトは Flutterwave）を選んで確定します。有効なメールアドレスが必要です。モジュールは、カートの通貨でカート合計額の Flutterwave 決済を作成し、購入者のメールアドレス、請求先住所の電話番号と氏名、ショップ名とロゴを渡して、購入者を Flutterwave の決済ページに移動させます。そこで購入者は、アカウントで有効な方法（または Payment Options に指定された方法）のいずれかで支払います。この時点では、注文はまだ存在しません。

支払い後、購入者は貴ショップに戻ります。注文は、Flutterwave が確認した後にのみ支払い済みとしてマークされます。ウェブフックによる確認、または購入者が戻ったときのサーバー側の確認によります。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。銀行振込、USSD、モバイルマネーなど支払いがまだ保留中の場合、注文は Awaiting Flutterwave payment で作成され、ページには 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. と表示されます。保留中の支払いが後で失敗し、購入者が確認ページを再度開いた場合は、Your Flutterwave payment was not completed. Please contact us about this order. と表示されます。

購入者が戻ったときに Flutterwave に接続できない場合、Payment confirmation ページに Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. と表示され、Check again と Back to checkout のボタンが表示されます。ウェブフックが届き次第、注文が作成されます。

支払いが拒否された場合、購入者はチェックアウトに戻り、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. などの短いメッセージが表示されます。技術的な理由はログに記録されます。

支払いと確認の間にカートが変更された場合（別のブラウザータブでの変更など）、金額が一致しなくなり、注文はメモ付きで Flutterwave payment on hold になります。

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

本モジュールは都度払いのみに対応しています。貴サイト内の埋め込み型やモーダル型のチェックアウト、保存済みカード、定期購入、分割決済、支払いプランには対応していません。ホスト型の決済リンクは Flutterwave API ではキャンセルできないため、カートの古いリンクは引き続き支払いに使用される可能性があります。

注文と返金

注文ステータス

注文はまだありません: 購入者は Flutterwave に移動しましたが、まだ支払っていないか、Flutterwave がまだ支払いを確認していません。カートのみが存在します。

Payment accepted or Delivered: 支払いが確認されました。Delivered は Autocomplete Orders がオンの場合に使用されます。支払いは Flutterwave の参照情報（flw_ref）を取引 ID として記録され、メモには金額、支払い方法、参照情報、取引、モードが表示されます。

Awaiting Flutterwave payment: 購入者は、Flutterwave で支払いがまだ保留中のときに戻りました。Flutterwave が支払いを確認すると、注文は支払い済みのステータスに移ります。

Flutterwave payment on hold: 確認された金額または通貨がカートと一致しなかった場合、または注文がキャンセルされた後に支払いが届いた場合です。支払いは、実際に支払われた金額で記録されます（Flutterwave が別の通貨で請求した金額ではありません）。メモに理由が記載されます。注文を処理するか、支払いを返金してください。返金済みまたはキャンセル済みの注文は、繰り返されたウェブフックによって再び開かれることはありません。

Payment error: 支払い保留中の注文の最新の支払い試行が、Flutterwave によって失敗またはキャンセルとして報告されました。メモに理由が表示されます。

Canceled: 貴店が設定します。キャンセルされた注文について Flutterwave が後から支払いを報告した場合、注文は Flutterwave payment on hold になります（上記を参照）。

Refunded: モジュールを通じて支払いが全額返金されました。

すでに支払い済みの注文に 2 件目の支払いが届いた場合、注文は変更されません。メモには、Flutterwave ダッシュボードで重複分を返金するよう示されます。

Flutterwave payment ブロック

注文ページには Flutterwave payment ブロックが表示され、参照情報（tx_ref）、取引 ID と Flutterwave の参照情報、モード、ステータスと支払い方法、支払い額と返金額、テスト決済用の Test mode バッジ、返金履歴、注文の Flutterwave notes が示されます。

返金

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

モジュールはクレジットメモを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、Flutterwave を通じて返金は行われません。

Flutterwave ダッシュボードで行った返金は、PrestaShop には同期されません。必要に応じて、注文ステータスを手動で更新してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Flutterwave が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、そして現在のモードの秘密キーが入力されていてモードと一致していることを確認してください。テストモードではテストキー（FLWSECK_TEST-…）、本番モードでは本番キー（FLWSECK-…）です。一致しない場合は、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているかを確認してください。

決済は完了したが、注文が作成されていない: ウェブフックが機能していません。Flutterwave ダッシュボードで、ウェブフック URL が使用しているモード（テストまたは本番）の Webhook URL に表示された URL と完全に一致しているか、その秘密ハッシュがモジュールの Secret Hash と同じかを確認してください。保留中の銀行振込、USSD、モバイルマネーは、Flutterwave が確認するまで保留のままです。購入者が支払い後にショップに戻った場合にも注文は作成されます。Debug log をオンにして、モジュールページの Log 欄を確認してください。

ウェブフックが Invalid hash または Secret hash not configured を返す: Flutterwave ダッシュボードの秘密ハッシュが、モジュールの値と異なるか、モジュールに設定されていません。両方に同じ値を入力してください。

ウェブフックが Verification failed、Busy、retry later、または Order could not be created, retry later を返す: 決済を検証するために Flutterwave に接続できなかったか、取引がまだ表示されていないか、カートが別のリクエストで処理中だったか、または注文を作成できませんでした（たとえばモジュールが無効になっている場合）。Flutterwave はウェブフックを再試行します。ログに理由が表示されます。

ウェブフック URL をブラウザーで開くと Empty body と表示される: これは正常です。この URL は Flutterwave からのウェブフックのみを受け付けます。

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

購入者に We could not match this payment to an order と表示される: 戻りリンクに、購入者のカートに属さない参照情報が含まれています。購入者から請求された場合は、Flutterwave ダッシュボードでその支払いを探してください。

Flutterwave のページにエラーが表示される、または購入者に Flutterwave could not start the payment と表示される: 貴店の Flutterwave アカウントが、カートの通貨または選択された支払いオプションに対応していない可能性があります。

支払い後に注文が Flutterwave payment on hold になる: Flutterwave payment ブロックのメモを確認し（注文ステータスを参照）、注文を処理するか、支払いを返金してください。

返金がモードに関するメッセージとともに失敗する: 支払いはテストモードまたは本番モードで行われており、そのモードの秘密キーが設定されていません。キーを入力してから再試行してください。

返金で Another operation on this payment is running と表示される: その時点で、同じ注文の別の返金が送信中でした。しばらく待ってから、返金履歴を確認し、必要であれば再試行してください。

開発者向けに、モジュールの README には、フック actionWcpFlutterwavePaymentRequest（Flutterwave に送信されるデータ）と actionWcpFlutterwaveCurrencyDecimals（通貨の精度）が記載されています。

アンインストール

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

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