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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Razorpay Payment，再点击 Configure。
3. 将您的 VibeFox 许可证密钥输入 Configure 页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。
4. 输入您的 Test Key ID 和 Test Key Secret，在 Razorpay Dashboard 中设置 Webhook，并输入其 secret（参见配置）。
5. 开启 Enable/Disable 并点击 Save。在开启 Test mode 的情况下进行一次测试付款。准备就绪后，输入正式（Live）密钥并关闭 Test mode。
安装时，模块会创建两个订单状态：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。
Webhook
即使顾客在付款后立即关闭浏览器，Webhook 也能确认付款，并记录在 Razorpay Dashboard 中进行的退款。在 Razorpay Dashboard 中进入 Account & Settings > Webhooks，分别在测试模式和正式模式下各添加一个 Webhook。使用本部分 Webhook URL 中显示的 URL。启用友好 URL 时，它类似于 https://your-shop/module/wcp_razorpay_payment/webhook，前面可能带有语言代码，例如 /en/。请完全按照设置中显示的内容复制。在 Razorpay 中输入您选择的 secret，并选择以下事件（本部分也列出了这些事件）：
Webhook Secret：创建 Webhook 时输入的 secret。测试和正式 Webhook 请使用同一个 secret，因为模块只为两者提供一个字段。没有有效签名的 Webhook 会被拒绝。如果没有 Webhook，只有在顾客从弹窗返回时，或顾客之后为同一购物车重新发起付款时，付款才会被确认。
高级
Enable Logging：日志写入模块文件夹中的 logs/razorpay_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会记录；此选项会额外添加调试详情。密钥、签名和顾客联系信息从不记录。默认：关闭。
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），模块会根据该笔付款创建订单，而不会再次要求付款。如果购物车总额已更改，则会创建一个新的 Razorpay 订单。
顾客可能看到的提示信息：
店铺处于维护模式时 Webhook 仍然有效，并且不受店铺国家限制的影响。
本模块仅支持一次性付款。不支持订阅或定期付款、已保存的银行卡、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 送达，并且只会在退款记录和备注中记录一次。订单全额退款后，其状态会变为 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 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工可以更改密钥。区块中的文字遵循后台语言（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用上次已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Razorpay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台不知道您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 标签页中会显示提醒。已有订单不受影响：已发起的付款仍会被确认，捕获和退款也仍然有效。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您操作后台时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 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 中显示的完全一致，以及五个事件是否均已选中。检查 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 的认可。