VibeFox Cashfree for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

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

HTTPS：Cashfree は https:// の URL にのみウェブフックを送信します。HTTPS がなくても、購入者がショップに戻ったときに支払いは確認されますが、本番運用の前に HTTPS を有効にしてください。

Cashfree アカウント：Cashfree アカウントの App ID と Secret Key が必要です。テスト環境（サンドボックス）と本番環境はそれぞれ別に用意してください。また、Cashfree Merchant Dashboard でウェブフックを設定する必要があります（設定を参照）。Secret Key はウェブフックの検証にも使われるため、ウェブフック用の別のシークレットはありません。カートの通貨は、Cashfree アカウントで有効になっている必要があります。

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

インストール

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

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

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

4. Sandbox App ID と Sandbox Secret Key を入力し、Cashfree Merchant Dashboard にウェブフックを追加し（設定を参照）、Enable/Disable をオンにして Save をクリックし、テスト決済を行います。

5. 準備ができたら、本番用の App ID と Secret Key を入力し、Sandbox Mode をオフにして Save をクリックします。

インストール時に、モジュールは注文ステータス Cashfree payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Cashfree Payments > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上には、注文は Cashfree が支払いを確認した後にのみ作成されることが説明されています。支払い方法が有効な場合、選択したモードの API キーがないと、ページに警告が表示されます（その場合、支払い方法はチェックアウトで非表示になります）。サンドボックスモードがオンの間は、Sandbox mode is on: customers see a test checkout and no real money is charged. が表示されます。選択したモードのキーがない状態で有効な支払い方法を保存すると、キーを入力するまでチェックアウトで非表示のままになる旨の警告が表示されます。

Cashfree Payments

Enable/Disable：Enable Cashfree Payments で支払い方法のオン・オフを切り替えます。既定値：off。

Title：購入者がチェックアウトで見る支払い方法の名前です。注文に保存される支払い方法名にもなります。既定値：Cashfree Payments。必須。

Description：チェックアウトで支払い方法の下に表示される文章です。既定値：Pay securely via Card, UPI, Net Banking, Wallet via Cashfree。

Mode and API keys

App ID と Secret Key は Cashfree Merchant Dashboard の Developers > API Keys で確認できます。テスト用のキーと本番用のキーは別々です。

Sandbox Mode：テストには Cashfree のサンドボックス環境を使用します。実際の料金は請求されず、チェックアウトの支払い方法の下に SANDBOX MODE - no real payments will be processed. が表示されます。既定値：on。本番の支払いではオフにしてください。

Sandbox App ID：Cashfree のテスト環境の App ID です。

Sandbox Secret Key：Cashfree のテスト環境の Secret Key です。

App ID：Cashfree の本番環境の App ID です。

Secret Key：Cashfree の本番環境の Secret Key です。

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

Clear saved secrets：Secret Key にチェックを入れて Save をクリックすると削除されます。入力欄を空にすると、保存済みの値は維持されます。

支払いは、作成時の環境を保持します。その支払いのウェブフックは、その環境のキーで検証され、ステータスも同じキーで確認され、返金も同じキーで送信されます。そのため、本番に切り替えた後もサンドボックスでの支払いが決済されるまでは、サンドボックスのキーを入力したままにしてください。

Webhook

ウェブフックは、支払いが完了したか、失敗したか、返金されたかをショップに通知します。Cashfree Merchant Dashboard で Developers > Webhooks に進み、このセクションの Webhook URL に表示された URL を、Payment と Refund のイベントとともに追加します。フレンドリー URL の場合は、次のような形になります：https://your-shop/module/wcp_cashfree_payment/webhook。URL は設定に表示されたとおりに正確にコピーしてください。HTTPS のショップでは、モジュールは支払いのたびにこの URL も Cashfree に渡します。ショップが HTTPS を使用していない場合、このセクションに警告が表示されます。

モジュールは次のイベントを処理します（これらはこのセクションにも記載されています）：

Cashfree は、すべてのウェブフックを Secret Key で署名します。有効な署名がないウェブフックは拒否されます。ウェブフックは、支払いが行われた環境の Secret Key で署名されている必要があります。そのため、サンドボックスのキーで本番の支払いが確認されることはありません。このショップが開始していない支払い（同じ Cashfree アカウントの別のショップによるものなど）の署名付きウェブフックは、受け付けたうえで無視されます。ウェブフックがない場合、注文は購入者が支払い後にショップに戻ったときにのみ作成されます。支払い後に購入者がブラウザを閉じた場合は、ウェブフック（または同じカートの次回の支払い試行）だけが注文を作成できます。

Advanced

API Version：使用する Cashfree API のバージョンです。

Order ID prefix：Cashfree の注文 ID は、プレフィックス + PrestaShop のカート ID で構成されます。同じカートに対する新しい試行には、末尾に番号が付きます（例：123-2）。フィールドの説明に表示されるこのショップの自動プレフィックスを使う場合は、空のままにしてください。同じ Cashfree アカウントに接続しているショップごとに、異なるプレフィックスを使用してください。使用できるのは英字、数字、「_」、「-」のみで、最大 20 文字です。それ以外の文字は、保存時に警告付きで削除されます。

Debug log：エラーは常に記録されます。オンにすると、Cashfree API の呼び出しとウェブフックも、モジュールのフォルダにある logs/cashfree_p_debug.log.php に書き込まれます。このファイルは Web から開くことはできません。キーや購入者データは記録されません。既定値：off。

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

Delete Data on Uninstall：オンにすると、モジュールをアンインストールしたときに Cashfree の設定とモジュールのログが削除されます。注文、その Cashfree の取引と返金、Cashfree payment on hold の注文ステータスは常に残るため、既存の注文は引き続き機能します。既定値：off。

チェックアウト

支払いの段階で、購入者は支払い方法（既定では Cashfree Payments）を選んで確定します。モジュールは、カートの合計額について、カートの通貨で Cashfree の注文を作成し、Redirecting to Cashfree for payment... と表示される支払いページを開いて、Cashfree のチェックアウトを読み込みます。自動では開かない場合、購入者は Pay Now をクリックできます。Cashfree のチェックアウトでは、購入者は Cashfree アカウントで有効になっている任意の方法（カード、UPI、ネットバンキング、ウォレットなど）で支払います。購入者のメールアドレスと請求先の電話番号は Cashfree に渡されます。この時点ではまだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文が支払い済みになるのは、Cashfree が支払いを確認した後だけです。署名付きのウェブフックによる確認、または購入者が戻ったときに Cashfree へサーバーから送られるリクエストによって確認されます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。購入者が UPI アプリから戻る場合など、別のブラウザで戻った場合も機能します。銀行による支払いの確認がまだの場合、Payment confirmation ページに Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. と Check again ボタンが表示されます。銀行が支払いを確認すると、ウェブフックによって注文が作成されます。

支払いが失敗した場合、または購入者が支払わずに Cashfree のページを離れた場合、購入者はチェックアウトに戻り、The Cashfree payment was not completed. Please try again or choose another payment method. と表示されます。カートは保持されます。購入者が再試行すると、未完了の Cashfree の支払いが再利用されます。カートの合計が変更された場合やセッションの期限が近い場合は、古い Cashfree の注文が閉じられ、新しい注文が作成されるため、カートが二重に支払われることはありません。カートが Cashfree で支払い済みだが記録されていない場合、次回の試行では再度請求されず、注文が作成されます。

Cashfree が支払いを開始できない場合、購入者はチェックアウトにとどまり、We could not start the Cashfree payment. Please try again or choose another payment method. と表示されます。技術的な理由はログに記録されます。Cashfree の最低額（通貨の 1 単位。BHD、JOD、KWD、OMR は 0.01、TND は 0.1）を下回るカートの合計は、Cashfree では支払うことができず、そのカートには支払い方法が表示されません。

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

本モジュールは、Cashfree のチェックアウトでの 1 回限りの支払いのみに対応しています。保存済みカード、定期購読や定期払い、オーソリとキャプチャの個別処理、Cashfree のオファーウィジェット、Cashfree 経由の代金引換（COD）や支払いリンクには対応していません。また、通貨換算もありません。カートはカートの通貨で請求されます。

注文と返金

Order statuses

No order yet：購入者は Cashfree に移動したものの支払っていない、支払いが失敗した、または支払いが銀行でまだ保留中です。存在するのはカートだけです。

Payment accepted：支払いが確認されました。支払いは、Cashfree の支払い ID を取引 ID として記録され、メモには取引 ID と支払い方法のグループ（例：upi や credit_card）が表示されます。

Cashfree payment on hold：Cashfree が、カートの合計額と異なる支払い金額または通貨を報告しました（例：支払いの開始後に、別のタブでカートが変更された場合）。メモには、想定された金額と受け取った金額、および取引 ID が表示されます。Cashfree のダッシュボードで支払いを確認したうえで、注文を処理するか、支払いを返金してください。

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

注文がキャンセルされた後に届いた支払いも記録され、お金が受け取られているため、注文は再び支払い済みになります。支払い済みの注文が、その後の失敗した支払いによって未払いに戻されることはありません。

Cashfree payment block

注文画面には Cashfree payment ブロックが表示されます。このブロックには、取引 ID、Cashfree の注文、支払いステータス、支払い済みと返金済みの金額、サンドボックスの支払い用の Sandbox バッジ、返金履歴、注文の Cashfree notes が含まれます。

Refunds

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

最終的な返金ステータスは返金用のウェブフックで届き、メモに追加されます。モジュールは貸方伝票を作成しません。注文画面にある PrestaShop の標準の返金ボタンでは、Cashfree を通じて返金されません。

ライセンスキー

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

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

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

トラブルシューティング

Cashfree がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードにキーが設定されていることを確認してください。サンドボックスモードでは Sandbox App ID と Sandbox Secret Key、本番モードでは App ID と Secret Key が必要です。キーがないと、設定ページに警告が表示されます。カートの合計が Cashfree の最低額を下回る場合も、支払い方法は非表示になります。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているかを確認してください。

支払いは完了したが、注文が作成されない：ウェブフックが動作していません。ショップが HTTPS を使用していること、Developers > Webhooks の URL が Webhook URL に表示されたものと完全に一致していること、Payment イベントが選択されていることを確認してください。設定の Secret Key が、支払いが行われた環境のものであることを確認してください。Cashfree のダッシュボードには、ウェブフックごとにショップからの応答が表示されます。注文は、購入者が支払い後にショップに戻ったときや、同じカートの次回の支払い試行時にも作成されます。

ウェブフックが Missing signature または Invalid signature を返す：呼び出しに有効な Cashfree の署名がなかったか、設定の Secret Key が支払いが行われた環境と一致していません。サンドボックスと本番のキーが入れ替わっていないか確認してください。

ウェブフックが Ignored を返す：ウェブフックの署名は正しいですが、このショップが開始したものではない支払いに関するものです（同じ Cashfree アカウントの別のショップなど）。各ショップに個別の Order ID prefix を設定してください。

ウェブフックが Busy, retry later を返す：同じ時点で別のリクエストが注文を作成していたか、注文を作成できませんでした（例：モジュールが無効になっている）。Cashfree はウェブフックを再試行します。理由を確認するには Debug log をオンにしてください。

購入者に The Cashfree payment page could not be loaded と表示される：ブラウザで Cashfree のスクリプトを読み込めませんでした（広告ブロッカーなどが原因の場合があります）。購入者は Pay Now をもう一度クリックするか、Choose another payment method をクリックできます。

購入者に We could not start the Cashfree payment と表示される：モジュールのページの Log 欄を確認してください。よくある原因は、選択したモードのキーが誤っている場合や、Cashfree アカウントで有効になっていない通貨を使用している場合です。

購入者に We could not verify the payment と表示される：戻りリンクがカートと一致しませんでした。料金が請求されていた場合でも、ウェブフックによって注文は作成されます。購入者が再度支払う前に、Cashfree のダッシュボードで支払いを確認してください。

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

サンドボックスまたは本番モードに関するメッセージが表示され、返金に失敗する：支払いはその環境で行われており、その API キーが設定されていません。キーを入力してもう一度お試しください。

アンインストール

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

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