VibeFox PayU India for WooCommerce — 帮助

系统要求

WordPress: 5.8 或更高版本。

WooCommerce: 6.0 或更高版本，已安装并启用。若未安装，插件将拒绝启用；若后续停用 WooCommerce，插件将不执行任何操作并在管理后台显示提示。

PHP: 8.0 或更高版本。

Store currency: 印度卢比（INR）。PayU India 仅以卢比扣款。对于其他币种，结账时该付款方式将被隐藏。

Phone number: PayU 的每笔付款都需要电话号码。请在结账页面将电话字段设为必填，或至少设为可见。

PayU India account: 您需要来自 PayU Dashboard > Payment Gateway > Key Salt Details 的 Merchant Key 和 Merchant Salt (v1)。将控制面板切换到 Test Mode 即可查看测试密钥对。请使用 Salt v1，而非 Salt v2。

Internet access to your site: 可选 Webhook 需要此项支持。若无此项，当顾客从 PayU 返回时订单即获确认。

VibeFox license key: 在 vibefox.net 购买。一个密钥仅适用于一个域名。

安装

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

2. 点击 Activate。

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

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

5. 输入测试 Merchant Key 和 Salt，以及正式 Merchant Key 和 Salt（参见配置）。

6. 推荐做法：在 PayU Dashboard > Webhooks 中，为成功和失败付款添加设置页面上显示的 Webhook URL。

7. 选择 Mode 并开启 Enable/Disable。在 Test 模式下测试付款，然后切换到 Live。

配置

所有设置均位于一个页面：WooCommerce > Settings > Payments > PayU India。若当前模式缺少密钥或 Salt，页面会在字段上方发出警告；在 Test 模式下显示 Test mode is active: payments go to test.payu.in and no real money is charged.；当店铺币种不是 INR 时也会发出警告（此时网关在结账时隐藏）。

保存时，密钥和 Salt 中的空格与换行符会被自动移除，因为带有空格的 Salt 会导致每次 PayU 响应校验失败。

常规

Enable/Disable: Enable PayU India Payment Gateway 用于开启或关闭该付款方式。默认：关闭。

Title: 顾客在结账时看到的付款方式标题。默认：PayU India。

Description: 顾客在结账时看到的付款方式描述。默认：Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU。

API 凭据

从 PayU Dashboard > Payment Gateway > Key Salt Details 复制 Merchant Key 和 Merchant Salt (v1)。将控制面板切换到 Test Mode 以获取测试密钥对。

Mode: 新付款所使用的 PayU 环境。

退款始终发送到发生付款时所使用的模式。

Live Merchant Key: 您的 PayU 正式环境 Merchant Key。

Live Merchant Salt (v1): 您的 PayU 正式环境 Merchant Salt (v1)。用于对请求进行签名并验证 PayU 响应。请妥善保密。

Test Merchant Key: 您的 PayU 测试 Merchant Key，仅在 Test 模式下使用。

Test Merchant Salt (v1): 您的 PayU 测试 Merchant Salt (v1)，仅在 Test 模式下使用。

返回与 Webhook URL

Return URL: 格式类似 https://your-site/wc-api/payu_p_callback/。每笔付款都会自动将其发送给 PayU；无需任何手动配置。

Webhook URL: 格式类似 https://your-site/wc-api/payu_p_webhook/。可选但建议配置：即使顾客在返回前关闭浏览器，它也能确认付款。在 PayU Dashboard > Webhooks 中将其添加为成功和失败付款的通知地址。请严格按照设置页面显示的 URL 进行复制。

高级

Verify Payment: Double-check every successful payment with the PayU verify_payment API。建议开启。如果无法完成核验，订单将被设为保留而不是标记为已付款。默认：开启。

Enable Logging: Log gateway events for troubleshooting。写入 WooCommerce > Status > Logs，来源为 wcp_payu_india_payment。错误和警告始终记录；此选项会添加其余事件。密钥、Salt 和顾客个人数据绝不记录。默认：关闭。

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted (orders are never deleted)。默认：关闭。

结账

顾客选择付款方式（默认为 PayU India）并提交订单。若订单缺少账单电话（或收货电话），顾客会看到 PayU India requires a phone number. Please enter your phone number and try again.。否则顾客将进入简短过渡页 Thank you for your order. You will be redirected to PayU to complete your payment.，该页面会向 PayU 托管结账发送已签名的付款请求。顾客在此通过银行卡、NetBanking、UPI 或电子钱包完成支付。

每个支付页面都会获取其独有的 PayU 交易 ID，并与金额和模式一起保存在订单上。在同一订单先前打开的旧支付页面上完成的付款仍会被接受。已付款、保留或已取消的订单绝不会生成新的支付表单，因此浏览器的返回按钮无法触发二次付款。

PayU 会在顾客返回时携带结果，且若已配置还会通过 Webhook 发送结果。仅在具有使用发起付款时所属模式的密钥和 Salt 生成的有效 PayU 哈希，且仅针对为该订单生成的交易 ID 时，结果才会被接受。开启 Verify Payment 后，成功的结果还会通过 PayU verify_payment API 进行校验。已付金额必须与订单总额（INR）精确匹配到派萨（paisa）。只有在 PayU 以此方式确认后，订单才会标记为已付款。插件处理以下 PayU 结果：

付款成功或处于待处理状态后，顾客会看到订单已接收页面。付款未成功后，顾客会返回结账页面并看到提示信息：Payment was not completed. Please try again or choose a different payment method.、Payment was cancelled. You may try again.，或者当无法核验结果时显示 We could not confirm the payment result. If your account was charged, please contact us before paying again.。这些提示信息在经典结账和结账区块中均可正常使用。

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

插件仅以 INR 计费，不支持多币种处理（MCP）。不支持保存银行卡或令牌化、WooCommerce Subscriptions、站内无缝（seamless）银行卡表单、EMI 分期或优惠管理，也不支持 PayU 一键结账。

订单与退款

订单状态

Pending payment: 顾客已被引导至 PayU，尚未付款。

Processing: 付款已确认。订单备注会显示 PayU 交易 ID（mihpayid）、付款模式和银行代码。订单的交易 ID 即为 PayU mihpayid。仅包含可下载虚拟商品的订单将变为已完成，符合 WooCommerce 默认行为。

On hold: 付款在 PayU 端仍处于处理中（UPI 或 NetBanking）、已付金额或币种与订单不一致、无法访问 verify_payment API 或其尚未确认付款，或者收到了已取消订单的付款。订单备注会说明具体原因。请在 PayU Dashboard 中核查该交易并完成或退款。若核验失败，订单将在下次结果送达时自动确认。

Failed: 付款被拒绝或取消。顾客可以重新付款。

若 PayU 对已付款订单报告另一笔成功的付款，备注会提示您在 PayU Dashboard 中对重复款项进行退款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via PayU India（按钮显示您的 Title）。支持全额和部分退款；金额必须大于零。退款将使用付款时所属模式的密钥和 Salt 通过 PayU 退款 API 发送，因此必须配置这些凭据。若 PayU 拒绝退款，WooCommerce 会显示 PayU 的消息，且不会记录退款。

PayU 会将退款加入队列并异步完成；顾客通常在 5–7 个工作日内收到款项。订单备注会显示金额、PayU 请求 ID 和原因。插件随后不会再次核查退款状态。

许可证密钥

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

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

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

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

故障排除

PayU India does not appear at checkout: 请检查许可证是否处于激活状态、Enable/Disable 是否已开启，以及所选 Mode 的密钥和 Salt 是否已填写。检查店铺币种（或「Pay for order」页面上的订单币种）是否为 INR。设置页面会针对其中每个问题显示警告。

The payment went through, but the order stays Pending payment: 顾客未返回店铺，且未送达任何 Webhook。请在 PayU Dashboard > Webhooks 中为成功和失败付款添加设置中的 Webhook URL，并确保其可从公网访问。

Webhook answers invalid_signature: PayU 哈希不匹配。请检查付款模式对应的密钥和 Salt 是否正确，并确认使用的是 Salt v1 而非 Salt v2。订单不会被更改。

Webhook answers not_configured: 缺少发起付款时所属模式的密钥或 Salt。输入它们；PayU 将重试 Webhook。

Webhook answers verify_unavailable: verify_payment API 尚无法确认付款。订单处于保留状态，下一次送达时将重新校验。

The customer sees PayU India requires a phone number: 请在结账时将电话字段设为必填或可见。系统会使用账单电话，若仅填写了收货电话则使用收货电话。

The order is On hold: 请查看订单备注。原因可能是待处理的 UPI 或 NetBanking 付款、金额或币种不匹配、校验失败或待定，亦或是针对已取消订单的付款。

Refund fails: PayU transaction ID not found for this order. 表示该订单不存在 PayU 付款。提示付款模式的 Merchant Key/Salt 未设置的消息意味着您必须先输入该模式的凭据。

Too little in the log: 错误和警告始终记录；开启 Enable Logging 亦可查看每次 PayU 请求和结果。

Developer hooks: payu_p_request_fields 过滤器可在签名之前修改付款请求字段；payu_p_icon 过滤器可更改结账图标。

The license block shows an error: 请按照区块中的提示进行操作。例如，若密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额并点击 Check now。若站点地址发生变更，点击 Check now 为新域名激活密钥。若无法连接许可证服务器，插件将按最后已知的状态继续运行。

卸载

停用插件会保留所有数据。若要彻底移除，请在 Plugins 页面停用并删除。该插件的许可证密钥和许可证状态始终会被清除。仅当开启了 Delete data on uninstall 时，网关设置和该插件的日志（日志文件和 WooCommerce 数据库日志中的记录行）才会被清除。否则它们会保留以供日后重新安装。现有订单会保留其付款备注、PayU 交易 ID 和退款请求 ID。

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