VibeFox Razorpay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并已启用。未安装 WooCommerce 时，插件无法启用。

PHP：8.0 或更高版本。

Razorpay 账户：测试模式需要您 Razorpay 账户的 Key ID 和 Key Secret；正式模式需要在账户激活后使用。强烈建议配置一个使用您自选密钥的 Webhook（参见「配置」）。使用 INR 以外的货币付款时，需要在您的 Razorpay 账户中启用 International Payments。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_razorpay_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Razorpay > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入您的 Test Key ID 和 Test Key Secret，在 Razorpay Dashboard 中设置 Webhook 并输入其密钥（参见「配置」）。

6. 启用 Enable/Disable，并在 Test mode 开启的情况下进行一次测试付款。准备就绪后，输入 Live 密钥并取消勾选 Test mode。

配置

所有设置都在同一个页面中：WooCommerce > Settings > Payments > Razorpay。页面在字段上方显示提示：当前模式的密钥缺失（此时付款方式在结账时隐藏）、测试模式下 Key ID 未以 rzp_test_ 开头或正式模式下未以 rzp_live_ 开头、测试模式已开启、Webhook 密钥为空，或店铺货币不是 INR 且需要在您的 Razorpay 账户中启用 International Payments。在付款方式列表中，Razorpay 会被标记为需要设置，直到当前模式具有其密钥；测试模式开启期间，会显示 Test mode 标记。粘贴密钥时带入的空格会在保存时被删除。

常规

Enable/Disable：Enable Razorpay Payment Gateway 用于启用或禁用该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。默认：UPI, Cards, NetBanking。

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：Use the Test mode keys (no real money is charged)。默认：开启。取消勾选即可接受真实付款。订单的付款、扣款和退款始终使用该订单付款时所在模式的密钥，因此之后切换模式不会影响现有订单。

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。

付款

Payment Action：扣款的时机。默认：Authorize & Capture。

Authorize & Capture：顾客立即付款。如果 Razorpay 报告付款已授权，插件会对其进行扣款（捕获）。

Authorize Only：款项被预留。订单会被设为 “保留”，您随后可通过订单操作 Capture Razorpay payment 或在 Razorpay Dashboard 中进行扣款。对于未能及时扣款的已授权付款，Razorpay 会自动退款。

Webhook

即使顾客在付款后立即关闭浏览器，Webhook 也能确认付款，并记录在 Razorpay Dashboard 中进行的退款。在 Razorpay Dashboard 中进入 Account & Settings > Webhooks，分别为测试模式和正式模式各添加一个 Webhook。使用本设置页面此部分显示的 URL，其格式类似 https://your-site/wc-api/razorpay_p_webhook/。请按设置中显示的内容完整复制。在 Razorpay 中输入您自选的密钥，并选择以下事件：

payment.authorized：付款已授权。

payment.captured：付款已扣款，包括在 Razorpay Dashboard 中扣款的情况。

payment.failed：付款尝试失败。

order.paid：该付款对应的 Razorpay 订单已付款。

refund.created：付款已退款，例如在 Razorpay Dashboard 中退款。

Webhook Secret：创建 Webhook 时输入的密钥。测试和正式 Webhook 请使用相同的密钥，因为插件只有一个字段用于两者。没有有效签名的 Webhook 会被拒绝。如果没有 Webhook，只有在顾客从弹窗返回或之后重新打开订单付款页面时，付款才会被确认。

高级

Enable Logging：Save debug logs。日志位于 WooCommerce > Status > Logs，来源为 wcp_razorpay_payment。错误和警告始终会被记录；此选项会添加调试详情。密钥、签名和顾客联系信息绝不会被记录。默认：关闭。

Delete Data on Uninstall：Remove the plugin settings and logs when the plugin is deleted (orders are never touched)。默认：关闭。

结账

顾客选择付款方式（默认为 UPI, Cards, NetBanking）并下单。插件会按订单的准确总额和币种创建一个 Razorpay 订单，并打开订单付款页面。Razorpay Checkout 弹窗会自动在该页面打开，并已预先填入顾客的姓名、电子邮件和电话。如果弹窗被关闭，顾客可以点击 Pay Now 重新打开，或点击 Cancel order。在测试模式下，页面会显示 Razorpay Test mode: no real money will be charged.

付款成功后，插件会验证 Razorpay 签名，通过 Razorpay API 获取付款信息，并将金额和币种与订单进行比对。只有 Razorpay 确认后，订单才会被标记为已付款。随后顾客会看到订单已接收页面。如果签名有效但当时无法获取付款信息，订单会被设为 “保留”，之后由 Webhook 确认。

如果顾客返回一个未付款的订单，插件会复用其 Razorpay 订单。如果该 Razorpay 订单已经付款（例如顾客关闭了浏览器且没有 Webhook），插件会应用这笔付款，而不是再次要求付款。

顾客可能看到的消息：

Payment was cancelled. Please click "Pay Now" to try again.

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

We could not verify your payment. 该消息补充说明：如果已扣款，Razorpay 确认后订单将自动更新。

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. 弹窗脚本被拦截；消息会提示检查网络连接、禁用内容拦截器并重新加载页面。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

本插件仅支持一次性付款。不支持订阅或定期付款、已保存的银行卡、Razorpay Magic Checkout、Payment Links 或 Route（分账付款），也不支持优惠或可负担性组件。

订单和退款

Order statuses

Pending payment：Razorpay 订单已创建，顾客尚未付款。每个 Razorpay 订单都会以其金额和模式添加到订单备注中。

Processing or Completed：付款已扣款并确认，付款后 WooCommerce 的默认状态。订单备注会显示 Razorpay 付款 ID、金额以及确认方式（回调、Webhook 或返回时的检查）。交易 ID 即 Razorpay 付款 ID（pay_...）。

On hold：在以下情况下设置，每种情况都会附带一条订单备注：付款仅获得授权（Authorize Only）、已付金额或币种与订单不符、付款已为已取消的订单扣款，或当时无法通过 Razorpay API 验证付款。已处于“保留”的订单同样会添加备注。

Failed：待付款订单收到了 payment.failed Webhook。备注会显示 Razorpay 的错误信息。顾客仍可再次付款；已有授权或扣款成功付款的订单不会被更改。

Cancelled：顾客点击了 Cancel order，或订单被您取消，或因 WooCommerce 库存保留超时而取消。之后到达的付款不会自动重新打开该订单：已授权的付款不会被扣款，已扣款的付款则会将订单设为“保留”以供您审核。

如果已付款的订单又收到额外付款，订单不会改变。备注会提醒您，如果这不是预期的，请在 Razorpay Dashboard 中退款。

扣款（Authorize Only）

打开处于“保留”的订单，在 Order actions 中选择 Capture Razorpay payment，然后点击更新按钮。付款将在授权时所在的模式中被扣款，订单随即变为已付款。如果 Razorpay 拒绝，订单备注会显示 Razorpay capture failed: 及原因。在 Razorpay Dashboard 中进行的扣款会通过 Webhook 完成订单。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via 加上付款方式的名称。支持全额和部分退款。退款将使用付款时所在模式的密钥发送。如果 Razorpay 不接受退款，WooCommerce 会显示 Razorpay refund failed: 及原因，并且不会记录任何退款。成功的退款会以 Razorpay 退款 ID、金额和状态添加到订单备注中。

在 Razorpay Dashboard 中进行的退款会通过 Webhook 送达，并以 WooCommerce 退款的形式记录在订单上，每笔只记录一次，且不会将商品重新入库。如果 Dashboard 中的退款使用的是其他币种，或金额超过可退金额，则不会自动记录；备注会提示您手动记录。

许可证密钥

本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Razorpay 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。点击 Check now 可重新检查状态，点击 Change key 可输入其他密钥，点击 Remove key 可将密钥从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放名额。

如果没有有效的密钥，结账时顾客不会看到 Razorpay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常进行。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时不显示 Razorpay：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否同时具有两个密钥：测试模式需要 Test Key ID 和 Test Key Secret，正式模式需要 Live Key ID 和 Live Key Secret。缺少密钥时，设置页面会显示提示。

付款已完成，但订单仍为 Pending payment：Webhook 没有正常工作。请在 Razorpay Dashboard 中检查您所用模式（测试或正式）下是否存在该 Webhook，其 URL 是否与设置中显示的完全一致，以及五个事件是否已全部选中。检查 Webhook Secret 是否与 Razorpay 中的密钥相同。顾客重新打开订单付款页面时，订单也会被确认。

Webhook 返回 Webhook secret not configured：Webhook Secret 为空。请输入 Razorpay Webhook 的密钥。Razorpay 之后会重新发送该事件。

Webhook 返回 Invalid signature 或 Missing signature：设置中的密钥与 Razorpay Webhook 的密钥不一致。请在两处输入相同的密钥。

Webhook 返回 Retry later：插件无法通过 Razorpay API 确认扣款，或订单当时正被另一个请求更新。Razorpay 会自动重新发送该事件。

订单处于 On hold：请阅读订单备注。付款仅获得授权（请使用 Capture Razorpay payment），金额或币种与订单不符，付款到达时订单已取消，或当时无法通过 Razorpay API 验证，并正在等待 Webhook。

顾客付款时看到错误：请打开订单备注，或查看 WooCommerce > Status > Logs，来源为 wcp_razorpay_payment。即使 Enable Logging 关闭，错误也会被记录。密钥错误会显示付款方式当前不可用的提示。Razorpay 的其他原因会显示在 Razorpay could not accept this payment: 之后。

弹窗无法打开：Razorpay Checkout 脚本被内容拦截器或网络连接拦截。顾客会看到提示，并可重新加载页面。

退款失败：退款使用付款时所在模式的密钥。请检查该模式的密钥是否已设置，并阅读错误信息中的原因。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件会沿用最后已知的状态继续工作。

卸载

停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置和日志（日志文件，包括轮转的日志，以及数据库中的日志记录）仅在 Delete Data on Uninstall 已开启时才会被删除；否则它们会保留，以便之后重新安装时使用。订单及其 Razorpay 数据永远不会被删除。现有订单会保留其付款备注和交易 ID。

Razorpay 是其各自所有者的商标。本插件与 Razorpay 无关，也未获得 Razorpay 的认可。