VibeFox PayU India for PrestaShop — 帮助
系统要求
PrestaShop: 8.0 至 9.x。
PHP: 8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
货币: 印度卢比（INR）。PayU India 仅以卢比计费。对于使用其他货币的购物车，结账时会隐藏该付款方式。
电话号码: PayU 要求每笔付款都提供电话号码。请在您的结账页面中将地址的电话字段设为必填，或至少设为可见。
PayU India 账户: 您需要从 PayU Dashboard > Payment Gateway > Key Salt Details 获取 Merchant Key 和 Merchant Salt (v1)。将仪表板切换到 Test Mode 可查看测试密钥对。请使用 Salt v1，而非 Salt v2。
店铺的互联网访问: 可选 Webhook 需要此项。没有它，订单会在顾客从 PayU 返回后确认。
VibeFox 许可证密钥: 在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox PayU India Payment Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入 Test Merchant Key 和 Salt，以及 Live Merchant Key 和 Salt（参见配置）。
5. 建议：在 PayU Dashboard > Webhooks 中，为成功和失败的付款添加 Configure 页面上显示的 Webhook URL。
6. 选择 Mode，开启 Enable/Disable，然后点击 Save。先在测试模式下测试付款，然后切换到正式模式。
安装时，模块会创建两个订单状态：Awaiting PayU India payment 和 PayU India payment on hold。PrestaShop 为所有币种、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中加以限制；但 INR 币种必须保持允许该模块使用。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会在当前模式的密钥或 Salt 缺失时提醒您，在测试模式下显示 Test mode is active: payments go to test.payu.in and no real money is charged.，并在店铺默认币种不是 INR 时显示错误（此时该网关在结账时隐藏）。
保存时，密钥和 Salt 中的空格与换行会被删除，因为粘贴时带有空格的 Salt 会导致每个 PayU 响应都无法通过校验。
PayU India
Enable/Disable: Enable PayU India Payment Gateway 用于开启或关闭该付款方式。默认：关闭。如果在没有当前模式密钥和 Salt 的情况下开启，页面会在保存后发出警告。
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 以获取测试密钥对。该部分有一个 Open the PayU Dashboard 链接。
Mode: 新付款使用的 PayU 环境。
已发起的付款会保留其发起时所用的模式：即使您之后切换了模式，这些付款的结果仍将使用该模式的密钥和 Salt 进行校验，退款也将使用其发起模式的密钥和 Salt 发送。
Live Merchant Key: 您的正式 PayU Merchant Key。
Live Merchant Salt (v1): 您的正式 PayU Merchant Salt (v1)。它用于签名请求并校验 PayU 响应。请妥善保密。
Test Merchant Key: 您的 PayU 测试 Merchant Key，仅在测试模式下使用。
Test Merchant Salt (v1): 您的 PayU 测试 Merchant Salt (v1)，仅在测试模式下使用。
已保存的 Salt 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved salts: 勾选某个 Salt 并点击 Save 即可将其删除。空字段会保留已保存的值。
返回和 Webhook URL
Return URL: 格式类似 https://your-shop/module/wcp_payu_india_payment/return，可能带有语言代码，例如 /en/。每笔付款都会自动发送给 PayU；无需进行任何配置。
Webhook URL: 格式类似 https://your-shop/module/wcp_payu_india_payment/webhook，可能带有语言代码。可选，但建议配置：即使顾客在返回前关闭了浏览器，它也能确认付款。请在 PayU Dashboard > Webhooks 中为成功和失败的付款添加该地址。请完全按照 Configure 页面显示的样子复制 URL。它必须可从互联网访问（不能有基本认证或防火墙拦截）。店铺的维护模式和国家限制不会阻止它。
Webhook 携带的签名结果与顾客返回时的相同。没有有效 PayU 哈希的 Webhook 会被拒绝。
高级
Verify Payment: 通过 PayU verify_payment API 对每笔成功付款进行二次校验。建议开启。如果无法完成校验，订单将被置于保留状态，而不会被标记为已付款。默认：开启。
Enable Logging: 将网关事件记录到模块文件夹中的 logs/payu_p_debug.log.php，用于故障排查。该文件无法通过网页访问。错误和警告始终会被记录；此选项还会添加其他事件，例如每个付款表单和每个 PayU 结果。密钥、Salt 和顾客个人数据绝不会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete data on uninstall: 卸载模块时删除模块设置和日志。订单和 PayU 交易记录绝不会被删除。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 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 托管结账页面。如果浏览器没有自动继续，页面上会有 Pay with PayU 按钮和 Back to checkout 按钮。在 PayU 页面上，顾客使用银行卡、NetBanking、UPI 或电子钱包付款。此时尚未创建订单。
每次付款尝试都会获得一个独立的 PayU 交易 ID，该 ID 以购物车编号开头，并与金额和模式一起保存。在同一购物车较早打开且仍然有效的付款页面中完成的付款仍会被接受。已有订单的购物车绝不会再获得新的付款表单，因此浏览器的后退按钮无法发起第二次付款。
PayU 会将结果随顾客一起返回，若已配置，也会通过 Webhook 发送。只有在结果附带使用发起付款时所属模式的密钥和 Salt 生成的有效 PayU 哈希，并且交易 ID 是为该购物车签发的情况下，结果才会被接受。开启 Verify Payment 时，成功的结果还会通过 PayU verify_payment API 进行校验。已付金额必须与尝试金额及购物车总额以 INR 计精确到派萨（paisa）一致。只有 PayU 以此方式确认后，订单才会被标记为已付款。模块处理以下 PayU 结果：
付款成功或待处理后，顾客会看到标准的订单确认页面。待处理的付款会附加 Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.；保留中的订单会附加 Your payment is being reviewed. We will contact you if anything else is needed.；处于 Payment error 或 Canceled 状态的订单会显示 Your PayU payment was not completed. Please contact us about this order.
付款未成功后，顾客会返回结账页面并看到以下消息之一：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. 如果顾客返回时结果仍在处理中，将显示一个页面，内容为 We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. 并附带 Check again 按钮。
模块仅以 INR 计费，不支持多币种处理（MCP）。不支持保存银行卡或令牌化、订阅、站内（seamless）银行卡表单、EMI 分期或优惠管理，也不支持 PayU 一键结账。
订单与退款
订单状态
No order yet: 顾客已被重定向至 PayU 但尚未付款，或付款失败或被取消。此时仅存在购物车。
Payment accepted: 付款已确认。付款以 PayU 交易 ID（mihpayid）作为交易 ID 记录，并显示备注 PayU payment successful. Transaction ID: …, Mode: …, Bank: …
Awaiting PayU India payment: UPI 或 NetBanking 付款仍在 PayU 处等待。PayU 确认后，订单将变为 Payment accepted。
PayU India payment on hold: 已付金额或币种与购物车不符，verify_payment API 无法访问或尚未确认付款，或者有付款到达了一个已被取消的订单。备注会说明原因。请在 PayU Dashboard 中核查交易，然后将订单设为 Payment accepted，或取消订单并退还付款。如果只是校验失败，则会在下一次结果送达时自动付款。
Payment error: 待处理的付款之后被拒绝或取消。之后成功的结果仍然会为订单付款。
Refunded: 已付的全部款项已通过模块退还。
如果 PayU 报告某个已付款订单又有另一笔成功付款，订单不会被更改，并会有备注提示您在 PayU Dashboard 中退还重复付款。对于使用其他付款方式下单的购物车所产生的 PayU 付款，会有备注，且不会为该订单付款。
PayU India 付款区块
订单页面会显示一个 PayU India payment 区块，其中包括 PayU 交易 ID（mihpayid）、店铺交易 ID（txnid）、环境、PayU 状态、付款模式和银行、已付金额和已申请退款金额、用于测试付款的 Test mode 标识、退款历史以及模块备注。对于保留中的订单，会显示提醒您检查付款。
退款
在 PayU India payment 区块中输入金额（会自动填入尚未退还的金额），可选填写原因，然后点击 Refund via PayU。确认提示 Refund this amount through PayU? This cannot be undone. 支持全额和部分退款；金额必须大于零，且不得超过 PayU 已收取金额的剩余部分。您需要具有编辑订单的权限；无需访问模块页面。退款通过 PayU 退款 API 发送，使用付款时所用模式的密钥和 Salt，因此必须已设置这些凭据。如果 PayU 拒绝退款，该区块会显示 PayU refund failed: 以及 PayU 的消息，且不会记录任何退款。
PayU 会将退款排队并异步处理；顾客通常在 5–7 个工作日内收到款项。退款历史和备注会显示金额、PayU 请求 ID 和原因。全额退款会将订单设为 Refunded；部分退款不会更改状态。一旦 PayU 报告了付款的交易 ID，即可进行退款。模块之后不会检查退款状态，也不会生成退款单（credit slip）。订单页面上 PrestaShop 的标准退款按钮不会通过 PayU 退款。
许可证密钥
模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayU India Payment Gateway 是 Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure 页面中位于设置上方的第一个区块。在 License key 中输入密钥，然后点击 Activate。此后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方有一行 Product: presta-payment-payu-india，以及一个链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 PayU India。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会通过通知得到确认，退款也能正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续期。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时不显示 PayU India: 请检查许可证是否有效，Enable/Disable 是否开启，以及所选 Mode 的密钥和 Salt 是否已填写。请检查购物车币种是否为 INR，并在 Payment > Preferences 中检查模块是否允许该币种、顾客所在国家和客户组。Configure 页面会对缺失的凭据和非 INR 的店铺币种显示警告。
付款已完成，但未创建订单: 顾客没有返回店铺，也没有收到 Webhook。请将 Configure 页面中的 Webhook URL 添加到 PayU Dashboard > Webhooks 中，用于成功和失败的付款，并确保其可从互联网访问。
Webhook 返回 invalid_signature: PayU 哈希不匹配。请检查付款所属模式的密钥和 Salt 是否正确，并确认使用的是 Salt v1 而非 Salt v2。使用测试 Salt 签名的正式付款结果，或反过来的情况，同样会被拒绝。不会更改任何内容。
Webhook 返回 not_configured: 缺少付款发起所在模式的密钥或 Salt。请输入它们；PayU 会重试 Webhook。
Webhook 返回 verify_unavailable: verify_payment API 尚无法确认付款。订单处于保留状态，下一次送达时会再次校验。
Webhook 返回 busy 或 retry: 同一购物车的顾客返回正在同时处理，或订单无法创建（例如模块已禁用）。PayU 会重试 Webhook。原因会写入日志。
Webhook 返回 ignored_unknown_txnid: 该交易不是由本店铺发起的，例如另一家使用同一 PayU 账户的店铺。不会更改任何内容。
顾客看到 PayU India requires a phone number: 请在结账中将地址的电话字段设为必填或可见。会优先使用账单地址，其次是收货地址。
订单为 PayU India payment on hold: 请阅读 PayU India payment 区块中的备注。原因可能是金额或币种不符、校验失败或待处理，或是针对已取消订单的付款。
退款失败: PayU transaction ID not found for this order. 表示该订单尚无 PayU 付款。This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set.（或 Live mode）表示您必须先输入该模式的凭据。Invalid refund amount: at most … INR can be refunded. 表示金额超过了付款的剩余可退金额。
日志内容太少: 错误和警告始终会被写入；开启 Enable Logging 即可同时查看每个付款表单和每个 PayU 结果。
开发者钩子: actionPayuPRequestFields 会在付款请求字段签名前对其进行修改。密钥、交易 ID、金额和返回 URL 无法通过它更改。
卸载
进入 Modules > Module Manager，打开 VibeFox PayU India Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果开启了 Delete data on uninstall，模块设置和日志将被删除。如果关闭，所有设置都会保留，以便日后重新安装。PayU 交易记录、退款请求以及订单状态 Awaiting PayU India payment 和 PayU India payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和 PayU 交易 ID。
PayU 是其各自所有者的商标。本模块与 PayU 无关联，也未获得 PayU 的认可。