VibeFox Razorpay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは古い PHP バージョンへのインストールを拒否します。

Razorpay アカウント: テストモードでは Razorpay アカウントの Key ID と Key Secret が必要です。ライブモードでは、アカウントが有効化された後に必要になります。任意の secret を設定した Webhook の利用を強く推奨します（設定を参照）。INR 以外の通貨で決済するには、Razorpay アカウントで International Payments を有効にする必要があります。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Razorpay Payment を探し、Configure をクリックすることもできます。

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

4. Test Key ID と Test Key Secret を入力し、Razorpay Dashboard で Webhook を設定して、その secret を入力します（設定を参照）。

5. Enable/Disable をオンにして Save をクリックします。Test mode をオンにした状態でテスト決済を行います。準備ができたら、ライブ用のキーを入力し、Test mode をオフにします。

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

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Razorpay Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、現在のモードのキーが不足している（その場合、Razorpay はチェックアウトに表示されません）、テストモードで Key ID が rzp_test_ で始まっていない、またはライブモードで rzp_live_ で始まっていない、テストモードがオンになっている、Webhook secret が空である、ショップの既定の通貨が INR ではなく Razorpay アカウントで International Payments が必要になる、といった通知が表示されます。Key ID に貼り付けた余分なスペースは、保存時に削除されます。

Razorpay

Enable/Disable: Enable Razorpay Payment Gateway で、この決済方法のオン／オフを切り替えます。既定: オフ。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文に保存される決済方法名にもなります。既定: UPI, Cards, NetBanking。必須: 空欄にすると Enter a title for the payment method. というエラーになります。

Description: チェックアウトで決済方法の下に表示されるテキストです。既定: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

API キー

Razorpay Dashboard の Account & Settings > API Keys でキーを取得します。Dashboard をテストモードに切り替えると、テスト用キー（rzp_test_...）を生成できます。ライブ用キー（rzp_live_...）は、アカウントが有効化された後に利用できます。

Test mode: テストモードのキーを使用するため、実際の金額は請求されません。既定: オン。実際の決済を受け付けるにはオフにします。注文の決済、キャプチャ、返金は、その注文が支払われたモードのキーを常に使用します。そのため、後からモードを切り替えても既存の注文には影響しません。

Test Key ID: Razorpay Dashboard のテストモードにある Key ID です。rzp_test_ で始まります。

Test Key Secret: Razorpay Dashboard のテストモードにある Key Secret です。

Live Key ID: Razorpay Dashboard のライブモードにある Key ID です。rzp_live_ で始まります。

Live Key Secret: Razorpay Dashboard のライブモードにある Key Secret です。

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

保存済みの secret を消去: Test Key Secret、Live Key Secret、または Webhook Secret にチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が維持されます。

決済

Payment Action: 代金をいつ請求するかを指定します。既定: Authorize & Capture。

Authorize & Capture: 購入者にすぐ請求されます。Razorpay が決済の承認を報告すると、モジュールがその決済をキャプチャします。

Authorize Only: 金額は確保されるだけです。注文は Razorpay payment authorized ステータスで作成され、後で注文ページの Razorpay ブロックにある Capture Razorpay payment、または Razorpay Dashboard で決済をキャプチャします。期限内にキャプチャされなかった承認済みの決済は、Razorpay が自動的に返金します。

Webhook

Webhook は、購入者が支払い直後にブラウザを閉じた場合でも決済を確定させ、Razorpay Dashboard で行われた返金を記録します。Razorpay Dashboard で Account & Settings > Webhooks に移動し、テストモードの Webhook とライブモードの Webhook をそれぞれ追加します。このセクションの Webhook URL に表示される URL を使用してください。わかりやすい URL を有効にしている場合は、https://your-shop/module/wcp_razorpay_payment/webhook のような形式になり、/en/ などの言語コードが付くこともあります。設定に表示されたとおりに、正確にコピーしてください。Razorpay で任意の secret を入力し、次のイベントを選択します（これらはこのセクションにも記載されています）:

payment.authorized: 決済が承認されました。

payment.captured: 決済がキャプチャされました。Razorpay Dashboard でキャプチャした場合も含みます。

payment.failed: 決済の試行が失敗しました。

order.paid: 決済に対応する Razorpay の注文が支払い済みになりました。

refund.created: 決済が返金されました。たとえば Razorpay Dashboard での返金です。

Webhook Secret: Webhook の作成時に入力した secret です。モジュールにはテストと本番の両方に共通のフィールドが 1 つしかないため、テスト用 Webhook とライブ用 Webhook には同じ secret を使用してください。有効な署名のない Webhook は拒否されます。Webhook がない場合、決済が確定するのは、購入者がポップアップから戻ったとき、または購入者が同じカートの決済を後から再開したときだけです。

詳細設定

Enable Logging: ログは、モジュールのフォルダにある logs/razorpay_p_debug.log.php に書き込まれます。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。このオプションを有効にすると、デバッグの詳細も記録されます。キー、署名、購入者の連絡先情報は記録されません。既定: オフ。

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

Delete Data on Uninstall: オンにすると、モジュールのアンインストール時にモジュールの設定とログが削除されます。注文、Razorpay の取引と返金、およびモジュールの注文ステータスは常に残ります。既定: オフ。

チェックアウト

支払いの段階で、購入者は決済方法（既定では UPI, Cards, NetBanking）を選び、確定します。モジュールは、カートの合計金額と通貨に対応する Razorpay 注文を作成し、ショップの Razorpay payment ページを開きます。そのページで Razorpay Checkout のポップアップが自動的に開き、購入者の氏名、メールアドレス、電話番号が入力された状態になります。Razorpay の管理画面では、決済は Cart とカート番号として表示されます。この時点では、まだ PrestaShop の注文は存在しません。ポップアップが閉じられた場合、購入者は Pay Now をクリックしてポップアップを再度開いたり、Choose another payment method をクリックしてチェックアウトに戻ったりできます。カートは保持されます。テストモードでは、ページに Razorpay Test mode: no real money will be charged. と表示されます。

決済が成功すると、購入者には Please wait while we process your payment... と表示されます。モジュールは Razorpay の署名を検証し、Razorpay API から決済情報を取得して、金額と通貨をカートと照合します。注文は Razorpay による確認を得た後にのみ支払い済みとしてマークされます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。署名は有効でも、その時点で決済情報を取得できない場合は、注文が Razorpay payment on hold で作成され、後から Webhook が確認します。

購入者が同じカートの決済をやり直した場合、金額、通貨、モードが変わっていなければ、モジュールは既存の Razorpay 注文を再利用します。その Razorpay 注文が既に支払い済みの場合（たとえば購入者がブラウザを閉じ、Webhook もない場合）、モジュールは 2 回目の支払いを求めるのではなく、その決済から注文を作成します。カートの合計が変わっていた場合は、新しい Razorpay 注文が作成されます。

購入者に表示される可能性のあるメッセージ:

Your session has expired. Please click "Pay Now" to try again.

We could not verify your payment. 代金が引き落とされている場合、Razorpay が決済を確認すると注文が自動的に更新される旨が追記されます。

This payment method is not available right now. Please choose another payment method. キーが不足しているか、誤っています。

Razorpay is temporarily unavailable. Please try again in a few minutes.

Razorpay could not accept this payment: 続けて Razorpay から示された理由が表示されます。

The order amount is too small to be paid with Razorpay.

Razorpay Checkout could not be loaded. ポップアップのスクリプトがブロックされています。メッセージは、接続を確認し、コンテンツブロッカーを無効にして、ページを再読み込みするように求めます。

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

本モジュールは 1 回限りの決済のみに対応しています。定期購入や継続課金、保存済みカード、Razorpay Magic Checkout、Payment Links、Route（分割決済）には対応していません。また、オファーやアフォーダビリティのウィジェットにも対応していません。

注文と返金

注文ステータス

No order yet: 購入者がまだ支払っていないか、Razorpay がまだ決済を確認していません。存在するのはカートだけです。決済の試行が失敗しても注文は作成されません。購入者は再度支払うことができます。

Payment accepted: 決済がキャプチャされ、確認されました。決済は Razorpay の決済 ID（pay_...）を取引 ID として記録され、メモには決済 ID、金額、確認方法（callback、webhook、sync、admin）が表示されます。

Razorpay payment authorized: 決済は承認されただけです（Authorize Only）。注文を完了するにはキャプチャしてください。

Razorpay payment on hold: 次の場合に設定され、それぞれにメモが付きます。支払われた金額または通貨がカートと一致しない（たとえば、決済の開始後にカートが変更された）、キャンセル済みの注文に対して決済がキャプチャされた、またはその時点で Razorpay API を通じて決済を検証できなかった場合です。注文の通貨で支払われた金額は注文に記録されます。注文を確認して処理するか、決済を返金してください。

Cancelled: キャンセル済みの注文に対して後から届いた決済は、注文を自動的に再開しません。承認済みの決済はキャプチャされず、メモが付くだけです。キャプチャ済みの決済は、注文を Razorpay payment on hold にします。既に支払い済みの注文に対して同じ決済の通知が繰り返し届いても、注文をその後キャンセルしていても何も変更されません。

Refunded: 決済が全額返金されました。

既に支払い済みの注文に追加の決済が届いた場合、注文は変更されません。意図したものでなければ、Razorpay Dashboard で返金するよう、メモで案内されます。支払い済みの注文に対して遅れて届いた payment.failed は、メモを追加するだけです。

Razorpay 決済ブロック

注文ページには Razorpay payment ブロックが表示されます。ブロックには、Razorpay の決済 ID、Razorpay の注文、決済ステータス、Paid / refunded（Razorpay が請求した金額と返金済みの金額）、テスト決済用の Test mode バッジ、返金履歴、注文の Razorpay notes が含まれます。キャプチャと返金には注文を編集する権限が必要です。モジュールの設定へのアクセス権は必要ありません。

キャプチャ（Authorize Only）

ステータスが Razorpay payment authorized の注文を開き、Razorpay ブロックの Capture Razorpay payment をクリックして確定します。決済は承認されたモードでキャプチャされ、注文は Payment accepted になります。Razorpay が拒否した場合、ブロックとメモに理由とともに Razorpay capture failed: が表示されます。Razorpay Dashboard で行ったキャプチャは、Webhook を通じて注文を完了させます。

返金

Razorpay ブロックに金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Razorpay をクリックします。確認画面の Refund this amount through Razorpay? This cannot be undone. で確定してください。全額返金と一部返金に対応しています。返金は Razorpay が請求した金額と通貨で行われます。そのため、金額に不一致があった場合は、注文の合計ではなく、購入者が実際に支払った金額まで返金できます。より大きな金額を指定すると、Invalid refund amount: at most と、その上限額が表示されます。返金は、決済が行われたモードのキーで送信されます。Razorpay が返金を受け付けない場合、ブロックには Razorpay refund failed: と理由が表示され、返金は記録されません。返金に成功すると、Razorpay の返金 ID、金額、ステータスとともに、返金履歴とメモに追加されます。全額返金すると、注文のステータスは Refunded になります。一部返金では、ステータスは変わりません。返金は決済がキャプチャされた後に利用できます。

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

Razorpay Dashboard で行われた返金は Webhook によって届き、返金履歴とメモに 1 回だけ記録されます。注文が全額返金されると、そのステータスは Refunded になります。別の通貨の返金、または返金可能額を超える Dashboard の返金は自動的には記録されません。その場合はメモが表示され、手動で記録するよう求められます。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Razorpay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに両方のキーがあることを確認してください。テストモードでは Test Key ID と Test Key Secret、ライブモードでは Live Key ID と Live Key Secret が必要です。キーが不足している場合、設定ページに通知が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者の顧客グループに対してモジュールが許可されているかを確認してください。

決済は完了したが、注文が作成されなかった: Webhook が機能していません。Razorpay Dashboard で、使用しているモード（Test または Live）に Webhook が存在すること、その URL が Webhook URL に表示されたものと完全に一致すること、5 つのイベントすべてが選択されていることを確認してください。Webhook Secret が Razorpay の secret と同じであることも確認してください。購入者がポップアップから戻った場合、または同じカートの決済を再開した場合も、注文は作成されます。

Webhook が Webhook secret not configured と応答する: Webhook Secret が空です。Razorpay Webhook の secret を入力してください。Razorpay は後でイベントを再送します。

Webhook が Invalid signature または Missing signature と応答する: 設定の secret が Razorpay Webhook の secret と異なります。テスト用とライブ用の両方の Webhook について、両方の場所に同じ secret を入力してください。

Webhook が Retry later と応答する: モジュールが Razorpay API でキャプチャを確認できなかった、注文を作成できなかった（たとえばモジュールが無効になっている）、またはカートが同時に別のリクエストによって更新されていた、のいずれかです。Razorpay はイベントを自動的に再送します。理由は Log に記録されています。

ブラウザで Webhook URL に Method not allowed と表示される: これは正常な動作です。この URL は Razorpay からのリクエストのみを受け付けます。

注文が Razorpay payment on hold になっている: Razorpay ブロックのメモを確認してください。金額または通貨がカートと一致しなかった、キャンセル済みの注文に対して決済が届いた、またはその時点で Razorpay API を通じて検証できず、Webhook を待っている、のいずれかです。

購入者が支払い時にエラーを見る: モジュールのページにある Log 欄を確認してください。エラーは Enable Logging がオフでも記録されます。キーが誤っている場合は、その決済方法が現在利用できないというメッセージが表示されます。Razorpay のその他の理由は、Razorpay could not accept this payment: の後に表示されます。

ポップアップが開かない: Razorpay Checkout のスクリプトが、コンテンツブロッカーまたは接続によってブロックされています。購入者にはメッセージが表示され、ページを再読み込みできます。

キャプチャまたは返金がモードに関するメッセージで失敗する: 決済はテストモードまたはライブモードで行われましたが、そのモードのキーが設定されていません。キーを入力してから、もう一度お試しください。

アンインストール

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

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