VibeFox Flow for PrestaShop — ヘルプ

要件

PrestaShop：8.0～9.x。

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

通貨：チリペソ（CLP）または米ドル（USD）。それ以外の通貨のカートでは、チェックアウト時に決済方法が表示されません。CLP の場合は、International > Localization > Currencies で CLP 通貨の精度を 0 に設定してください。Flow は整数のペソで請求するためです。

Flow アカウント：Flow アカウントの API Key と Secret Key が必要です。Flow の Mis datos, Datos técnicos にあります。テスト用には sandbox.flow.cl で別のサンドボックスアカウントを作成し、そのキーを使用してください。サンドボックスキーと本番キーは異なります。Flow アカウント側で設定する必要はありません。

公開サイト：ショップの確認、戻り、返金の URL はインターネットから到達できる必要があります。パスワード保護や Flow をブロックするファイアウォールがあってはいけません。ショップのメンテナンスモードでもこれらの URL はブロックされません。

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

インストール

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

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

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

4. サンドボックスの API Key と Secret Key を入力し、Enable / Disable をオンにして Save をクリックし、テスト注文を行います。

5. 実際の決済を受け付けるには、本番キーを入力して Sandbox mode をオフにします。

インストール時にモジュールは 2 つの注文ステータス、Awaiting Flow payment と Flow payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Flow Gateway > Configure。項目のある各セクションには専用の Save ボタンがあり、ページ全体が保存されます。項目の上部には、現在のモードのキーが空の場合（その場合、チェックアウトで Flow は表示されません）、ショップの既定通貨が CLP でも USD でもない場合、CLP 通貨に小数点以下の桁がある場合に警告が表示されます（価格、合計、返金が正確に一致するよう、精度を 0 に設定してください）。サンドボックスモードでは Sandbox mode — payments go to sandbox.flow.cl, no real money is charged. と表示されます。

Flow.cl

Enable / Disable：Enable Flow.cl payments で決済方法を有効または無効にします。既定値：off。

Title：チェックアウトで購入者に表示される決済方法の名前です。注文にも決済方法名としてこの名前が保存されます。既定値：Flow。必須。

Description：チェックアウトで決済方法の下に表示されるテキストです。既定値：Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

Flow API 認証情報

Flow アカウント（Mis datos, Datos técnicos）から API Key と Secret Key をコピーします。本番キーは www.flow.cl、サンドボックスキーは sandbox.flow.cl（別のサンドボックスアカウント）から取得します。

Sandbox mode：Flow のサンドボックス（sandbox.flow.cl）とサンドボックスキーを使用します。サンドボックスモードでは実際の料金は請求されません。既定値：on。オフにして本番キーを入力すると、実際の決済を受け付けます。返金には常に注文が決済された環境を使用します。

Sandbox API Key：sandbox.flow.cl アカウントの API Key です。

Sandbox Secret Key：sandbox.flow.cl アカウントの Secret Key です。すべてのリクエストに署名するために使用されます。

Live API Key：www.flow.cl アカウントの API Key です。

Live Secret Key：www.flow.cl アカウントの Secret Key です。機密情報として管理してください。

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

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

通知

モジュールは、決済や返金のたびに 3 つの URL を Flow に送信するため、Flow アカウントで設定する必要はありません。このセクションの Flow URLs フィールドにこれらの URL が表示されます。フレンドリー URL が有効な場合、次のような形式になります。

確認通知には決済トークンだけが含まれます。モジュールは、自身が作成した決済の中からトークンを検索し、決済が作成された環境で署名付きリクエストを使って Flow に決済ステータスを問い合わせ、Flow の応答のみを適用します。このショップが作成していない決済は、Flow に問い合わせることなく拒否されます。確認通知がない場合は、購入者が Flow から戻った時点で注文が作成されます。

詳細設定

Debug log：API の呼び出しと通知を、モジュールフォルダ内の logs/flw_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。キーや購入者データは決してログに記録されません。エラーはオフの場合でも常に記録されます。既定値：off。

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

Delete data on uninstall：オンにすると、モジュールのアンインストール時に設定とログが削除されます。注文に保存された Flow のデータは保持されます。既定値：off。

チェックアウト

決済ステップで、購入者は決済方法（既定では Flow）を選択し、説明を確認します。サンドボックスモードでは SANDBOX MODE と表示され、支払いは Flow のサンドボックスに送られます。実際の請求は発生しません。確定すると、モジュールはカートの通貨でカート合計額の Flow 決済を作成します。件名は Cart # に続けてカート番号とショップ名です。その後、購入者を Flow の決済ページに移動させます。購入者のメールアドレスは Flow に渡されます。購入者は Flow ページで、お使いの Flow アカウントで有効な決済方法を選択します。この時点ではまだ注文は存在しません。

決済後、購入者はショップに戻ります。注文が支払い済みとしてマークされるのは、Flow が確認した後だけです。確認通知によるか、購入者の戻り時に署名付きステータスリクエストによって確認されます。その後注文が作成され、購入者には標準の注文確認ページが表示され、Your payment with Flow has been received. と表示されます。購入者が Servipag または Multicaja のクーポンを発行した場合、注文は Awaiting Flow payment で作成され、ページには Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. と表示されます。クーポン注文の支払いが後に失敗するか取り消された場合、ページには Your Flow payment was not completed. Please contact us about this order. と表示されます。金額が一致しなかった場合、ページには Your Flow payment was received and is being reviewed by the shop. と表示されます。

購入者が戻った時点で Flow に接続できない場合、またはその時点で別のリクエストが注文を作成している場合、Payment confirmation ページが表示され、再度支払わないよう求めるとともに、Check again と Back to checkout のボタンを提供します。

決済が拒否された場合、購入者は Your Flow payment was rejected. Please try again or choose another payment method. と表示されたチェックアウトに戻ります。購入者が支払わずに Flow のページを離れた場合、メッセージは The Flow payment was not completed. You can try again or choose another payment method. です。結果を確認できなかった場合のメッセージは We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. です。カートは保持され、再試行のたびにカートに紐づく新しい Flow 決済が作成されます。

Flow が決済を開始できない場合、購入者はチェックアウトに留まり、Could not connect to Flow. Please try again in a moment. などの短いメッセージが表示されます。詳細はログに記録されます。

決済と確認の間にカート内のクーポンが無効になった場合、PrestaShop はそのクーポンを注文から削除します。購入者は割引価格で支払っているため、注文はメモ付きで Flow payment on hold になります。

本モジュールは単発決済のみを受け付けます。保存済みカード、サブスクリプション、継続課金、決済リンクには対応しておらず、Flow の決済方法を事前選択することもありません。Flow は、作成済みの決済リンクをキャンセルできません。カートがすでに支払い済みの後に購入者が古いリンクで支払った場合、注文には重複した決済を Flow で返金するよう求めるメモが付きます。

注文と返金

注文ステータス

No order yet：購入者は Flow に移動しましたが、まだ支払っていないか、Flow がまだ決済を確認していません。存在するのはカートだけです。

Payment accepted：Flow が決済済みと報告し、金額と通貨が一致しています。決済は Flow の注文番号を取引 ID として記録され、メモには金額、Flow の注文番号、決済方法が表示されます。

Awaiting Flow payment：購入者が Servipag または Multicaja の支払いクーポンを発行しました。Flow が決済を確認すると、注文は Payment accepted に移ります。

Flow payment on hold：Flow が注文合計と異なる金額または通貨を報告した場合（例：決済の開始後にカートが変更された）、クーポンが削除された場合、またはキャンセル済みの注文に対して決済が届いた場合です。Flow が受け取った決済は記録され、メモで状況が説明されます。注文を確認し、出荷するか決済を返金してください。

Payment error：Flow が、保留中の注文のクーポン決済を拒否しました。

Canceled：保留中の注文のクーポン決済が Flow で取り消されました。

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

すでに支払い済みの注文に別の決済が届いた場合、注文は変更されません。メモで、Flow アカウントで重複した決済を返金するよう求められます。返金済みの注文が再開されることはありません。

Flow 決済ブロック

注文ページには Flow payment ブロックが表示され、Flow の注文番号と決済方法、commerceOrder の参照番号、決済ステータス、支払い額と返金額、サンドボックス決済用の Sandbox バッジ、返金履歴、注文の Flow notes が含まれます。

返金

Flow payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Flow をクリックします。Refund this amount via Flow? Flow e-mails the customer to complete the refund. の確認に答えます。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金額は Flow が実際に請求した金額に制限されます。そのため、金額が一致しない場合は、注文合計ではなく購入者が支払った金額まで返金できます。CLP の返金は整数の金額である必要があります。返金は決済が行われた環境（サンドボックスまたは本番）に送信されるため、その環境のキーが設定されている必要があり、購入者には有効なメールアドレスが必要です。Flow が返金を拒否した場合、ブロックにエラーが表示され、返金は記録されません。成功したリクエストは、Flow の返金番号とステータスとともに返金履歴とメモに追加されます。全額返金すると注文は Refunded になります。一部返金ではステータスは変わりません。返金は Flow が決済を確認した後に利用できます。

Flow が報告する返金ステータスの後続の変更は、メモに追加されます。その後 Flow が返金を拒否またはキャンセルした場合、メモには購入者に返金されていないことが記載され、その金額は再度返金できます。モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop の返金ボタンでは、Flow を通じた返金は行われません。Flow ダッシュボードで作成された返金は PrestaShop にインポートされません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Flow が表示されない：ライセンスが有効か、Enable / Disable がオンか、現在のモードのキーが入力されているか（サンドボックスモードではサンドボックスキー、本番モードでは本番キー）、カートの通貨が CLP または USD かを確認してください。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているかを確認してください。

決済は完了したが注文が作成されない：Flow の確認通知がショップに届いておらず、購入者も戻っていません。Flow URLs に表示されている確認 URL がインターネットから開けるか、パスワード保護やファイアウォールでブロックされていないかを確認してください。Debug log をオンにして、モジュールページの Log フィールドを確認してください。

確認通知の応答 Payment does not belong to the order：このトークンはこのショップが作成した決済ではないか、Flow がこの決済に別の参照を報告しました。何も変更されません。

確認通知の応答 Gateway not configured：決済の環境のキーが空です。もう一度入力してください。Flow は確認通知を再送します。

確認通知の応答 Flow API unavailable or Busy, retry：Flow へのステータスリクエストが失敗したか、同じタイミングで別のリクエストが注文を作成していました。Flow は確認通知を再送します。

購入者に Flow payments are not available at the moment と表示される：キーが未設定か、Flow がキーを拒否しました。現在のモードの API Key と Secret Key を確認してください。

購入者に A valid billing email is required for Flow payments と表示される：Flow には購入者のメールアドレスが必要です。

購入者に The order total is too small to be paid with Flow と表示される：カートの合計額がカートの通貨で四捨五入すると 0 になります。

購入者は支払ったが、注文が Awaiting Flow payment または Flow payment on hold になっている：Flow payment ブロックのメモを確認してください。購入者が未払いの現金クーポンを発行したか、Flow が報告した金額または通貨が注文と一致しません。小数点を含む CLP の合計額は整数のペソに四捨五入されるため、CLP の精度を 0 に設定してください。

サンドボックスまたは本番キーに関するメッセージで返金が失敗する：注文はその環境で決済されており、そのキーが空です。キーを入力してから再試行してください。

Flow accepts CLP refunds in whole units only で返金が失敗する：整数の金額を入力してください。

開発者向けに、README には次のフック（actionWcpFlowSupportedCurrencies：決済方法を提供する通貨、actionWcpFlowPaymentSubject：Flow に送信される決済の件名）が記載されています。

アンインストール

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

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