VibeFox Cashfree for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

WooCommerce: 6.0 以降がインストールされ、有効になっていること。これがないと、プラグインは有効化できません。

PHP: 8.0 以降。

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

Cashfree アカウント: テスト（サンドボックス）環境と本番環境それぞれについて、Cashfree アカウントの App ID と秘密キーが必要です。また、Cashfree Merchant Dashboard でウェブフックを追加する必要があります（「設定」の項を参照）。秘密キーはウェブフックの検証にも使用されるため、別のウェブフック用シークレットはありません。注文通貨が Cashfree アカウントで有効になっている必要があります。

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

インストール

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

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

3. 設定を開きます: WooCommerce > Settings > Payments > Cashfree Payments > Manage。または、プラグインページでプラグイン名の下にある Settings をクリックします。

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

5. Sandbox App ID と Sandbox Secret Key を入力し、Cashfree Merchant Dashboard でウェブフックを追加し（「設定」の項を参照）、Enable/Disable をオンにして、支払いをテストします。

6. 準備ができたら、本番の App ID と Secret Key を入力し、Sandbox Mode のチェックを外します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Cashfree Payments。支払い方法が有効な場合、選択したモードの API キーが欠けていると、ページに警告が表示されます（その場合、支払い方法はチェックアウトに表示されません）。サンドボックスモードがオンの間は、Sandbox mode is on: customers see a test checkout and no real money is charged. と表示されます。ゲートウェイが有効なのに選択したモードのキーがないまま保存すると、キーが設定されるまで支払い方法がチェックアウトに表示されないことを示すエラーメッセージが表示されます。

一般

Enable/Disable: Enable Cashfree Payments で支払い方法をオンまたはオフにします。既定値はオフです。

Title: チェックアウトで購入者に表示される支払い方法の名前。既定値: Cashfree Payments。

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

モードと API キー

App ID と秘密キーは、Cashfree Merchant Dashboard の Developers > API Keys で取得します。テスト用と本番用のキーは異なるため、それぞれ該当するセクションに入力してください。

Sandbox Mode: Enable Sandbox (test) mode により、テストには Cashfree のサンドボックスを使用します。実際の料金は請求されず、チェックアウトには SANDBOX MODE - no real payments will be processed. と表示されます。既定値はオンです。本番の支払いを受け付けるには、チェックを外してください。

サンドボックスの認証情報

Sandbox App ID: Cashfree のテスト環境の App ID。

Sandbox Secret Key: Cashfree のテスト環境の秘密キー。

本番の認証情報

App ID: Cashfree の本番環境の App ID。

Secret Key: Cashfree の本番環境の秘密キー。

注文は、作成された環境を保持します。それらのウェブフックは、その環境のキーで検証され、返金もそのキーで送信されます。そのため、本番に切り替えた後もサンドボックスの注文が清算されるまで、サンドボックスのキーは入力したままにしてください。

ウェブフック

ウェブフックは、支払いが行われた、失敗した、または返金されたことを貴店に知らせます。Cashfree Merchant Dashboard で Developers > Webhooks に移動し、この設定ページの本項に表示された URL を、Payment と Refund のイベントとともに追加します。URL は https://your-site/wc-api/cashfree_p/?action=webhook のような形式です。HTTPS のサイトでは、プラグインはこの URL を各注文とともに Cashfree にも渡します。サイトが HTTPS を使用していない場合、本項に警告が表示されます。

プラグインは次のイベントを処理します:

PAYMENT_SUCCESS_WEBHOOK: 支払いが成功しました。金額と通貨の確認後に、注文が支払い済みになります。

PAYMENT_FAILED_WEBHOOK: 支払いが失敗しました。注文は失敗になります。

PAYMENT_USER_DROPPED_WEBHOOK: 購入者が支払いを中断しました。メモが追加されます。購入者は引き続き再試行できます。

REFUND_STATUS_WEBHOOK and AUTO_REFUND_STATUS_WEBHOOK: 返金のステータスが変わりました。返金 ID、金額、ステータスを含むメモが追加されます。

Cashfree は、すべてのウェブフックに秘密キーで署名します。有効な署名のないウェブフックは拒否されます。このストアで作成されていない注文（例えば、同じ Cashfree アカウントの別のストア）に対する、署名付きのウェブフックは受領され、無視されます。ウェブフックがない場合、注文は、購入者が支払い後に貴店に戻ったときにのみ確認されます。購入者が支払い後にブラウザーを閉じた場合は、ウェブフックだけが注文を確認できます。

詳細設定

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

v1 (2022-09-01): 既定値。

v2 (2023-08-01): 新しい API バージョン。

Order ID prefix: Cashfree の注文 ID は、プレフィックス + WooCommerce の注文 ID で作られます。同じ注文に対する再試行には、末尾に番号が付きます。空欄のままにすると、フィールドの説明に表示されるこのサイトの自動プレフィックスを使用します。同じ Cashfree アカウントに接続されたストアごとに、別のプレフィックスを使用してください。使用できるのは英字、数字、「_」、「-」のみで、最大 20 文字です。それ以外の文字は、保存時にメッセージとともに削除されます。

Debug log: Log Cashfree API events for debugging。エラーは常に記録されます。オンの場合、API 呼び出しとウェブフックも WooCommerce > Status > Logs のソース wcp_cashfree_payment に記録されます。キーと購入者データは決して記録されません。既定値はオフです。

Delete Data on Uninstall: Delete all plugin data when uninstalling。オンの場合、プラグインを削除すると、Cashfree の設定、プラグインのログ、注文に保存された Cashfree の参照情報が削除されます。注文そのものは残ります。既定値はオフです。

チェックアウト

購入者は支払い方法（既定では Cashfree Payments）を選び、注文を確定します。プラグインは、注文通貨で注文合計額について Cashfree の注文を作成し、Pay for order ページを開きます。そこには Redirecting to Cashfree for payment... と表示され、Cashfree のチェックアウトが読み込まれます。自動で開かない場合、購入者は Pay Now をクリックできます。Cashfree のチェックアウトでは、購入者は Cashfree アカウントで有効になっている任意の方法（例: カード、UPI、ネットバンキング、ウォレット）で支払います。

支払い後、購入者は貴店に戻ります。注文が支払い済みになるのは、Cashfree が確認した後だけです。確認は、署名付きのウェブフック、または購入者が戻った際の Cashfree へのサーバー側のリクエストによって行われます。銀行がまだ支払いを確認していない場合、注文受付ページには Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. と表示されます。

支払いが失敗した場合、または購入者が支払わずに Cashfree のページを離れた場合、購入者は Pay for order ページに戻り、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 で支払うことができません。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文ストレージ（HPOS）に対応しています。購入者向けのテキストはヒンディー語に翻訳されています。

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

注文と返金

注文ステータス

Pending payment: 購入者は Cashfree に移動されましたが、まだ支払っていないか、銀行でまだ支払いが保留中です。保留中の支払いを伴って購入者が戻った場合、プラグインが Cashfree のウェブフックを待っていることを示すメモが表示されます。

Processing: 支払いが確認されました（仮想のダウンロード可能な商品のみの注文は、WooCommerce の既定の動作どおり完了になります）。注文メモには、Cashfree の取引 ID と支払い方法のグループが表示されます。注文の取引 ID は Cashfree の支払い ID です。注文がキャンセルされた後に届いた支払いも、お金は徴収されているため記録されます。

On hold: Cashfree が、注文合計と異なる支払い金額または通貨を報告しました。注文メモには、想定された金額と受け取った金額、取引 ID が表示されます。Cashfree のダッシュボードで支払いを確認し、注文を手動で完了するか返金してください。

Failed: 支払いが失敗したか、Cashfree でキャンセルされました。メモには、Cashfree のステータスと理由が表示されます。失敗した試行が 1 回行われるごとに、メモが 1 件追加されます。

支払い済みの注文が、後から届くウェブフックや戻りによって元に戻されることは決してありません。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Cashfree Payments をクリックします（ボタンには支払い方法のタイトルが表示されます）。全額返金と一部返金に対応しています。返金は、支払いが行われた Cashfree の注文に対して、支払われた環境（サンドボックスまたは本番）で送信されるため、その環境のキーが設定されている必要があります。Cashfree が返金を受け付けない場合、または返金をキャンセル済みや拒否済みと報告した場合、WooCommerce にエラーが表示され、返金は記録されません。開始された返金は、返金 ID、金額、ステータスとともに注文メモに追加されます。最終的なステータスは、返金のウェブフックによって、別の注文メモとして届きます。

返金ステータスのウェブフックは、メモとして追加されるだけです。WooCommerce の返金として自動的に記録されることはありません。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに Cashfree が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードのキーが設定されていることを確認してください。サンドボックスモードでは Sandbox App ID と Sandbox Secret Key、本番モードでは App ID と Secret Key です。注文合計が Cashfree の最低額を下回る場合も、支払い方法は非表示になります。キーが欠けている場合、設定ページに警告が表示されます。

決済は完了したが、注文が Pending payment のまま: ウェブフックが機能していません。サイトが HTTPS を使用していること、Developers > Webhooks の URL が設定に表示されたものと正確に一致すること、Payment のイベントが選択されていることを確認してください。設定の秘密キーが、注文が支払われた環境のものであることも確認します。注文は、購入者が支払い後に貴店に戻ったとき、および次の支払い試行時にも確認されます。

ウェブフックの応答 Missing signature または Invalid signature: この呼び出しには有効な Cashfree の署名がなかったか、設定の秘密キーが注文の作成された環境と一致しません。Cashfree はウェブフックを再送します。

ウェブフックの応答 Ignored: ウェブフックは正しく署名されていますが、このストアで作成されていない注文（例えば、同じ Cashfree アカウントの別のストア）に属しています。ストアごとに別の Order ID prefix を設定してください。

ウェブフックの応答 Busy, retry later: 同じ時刻に別のリクエストによって注文が処理されていました。Cashfree はウェブフックを再送します。

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

購入者に We could not start the Cashfree payment と表示される: Debug log をオンにして、WooCommerce > Status > Logs をソース wcp_cashfree_payment で確認してください。よくある理由は、選択したモードのキーが誤っている、または Cashfree アカウントで有効になっていない通貨を使っていることです。

購入者に The minimum amount for a Cashfree payment is … と表示される: 注文合計が、その通貨の Cashfree の最低額を下回っています。

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

支払い後に注文が On hold になっている: 注文メモを読んでください。支払われた金額または通貨が、注文と異なっていました。注文を完了するか、支払いを返金してください。

返金が失敗する（sandbox または live モードに関するメッセージ）: 注文はその環境で支払われており、その API キーが設定されていません。キーを入力してから、再度お試しください。

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

アンインストール

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

Cashfree は、それぞれの所有者の商標です。このプラグインは Cashfree と提携しておらず、Cashfree による推奨も受けていません。