VibeFox PayU India for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

货币：印度卢比（INR）。PayU India 仅以卢比收款。您的店铺需要 INR 货币（System > Localisation > Currencies）。对于其他货币的订单，结账时会隐藏该付款方式。

电话号码：PayU 要求每笔付款都提供电话号码。请在结账中保留 Telephone 字段，使订单具有电话号码。在 OpenCart 4 中，结账默认不要求电话号码：如果订单中没有电话号码，扩展会在确认步骤中显示自己的 Phone 字段（参见「结账」）。

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 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_payu_india_payment-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_payu_india_payment.ocmod.zip。只安装与您 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payu_india_payment-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayU India Payment Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块的 License key 中，然后点击 Activate（参见许可证密钥）。

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

5. 建议：在 PayU Dashboard > Webhooks 中，为成功和失败的付款添加设置页面上显示的 Webhook URL。

6. 选择 Mode，开启 Enable/Disable，然后点击 Save。在 Test 模式下测试一笔付款，然后切换到 Live。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payu_india_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayU India Payment Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 3–6 步输入许可证密钥、PayU 凭据和 Webhook。设置页面及其字段在两个版本中相同。仅返回和 Webhook URL 不同（参见「返回和 Webhook URL」）。

新安装默认关闭付款方式，并选中 Test 模式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox PayU India Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当当前模式的密钥或 salt 缺失时，页面会向您发出警告；在 Test 模式下，页面会显示 测试模式已启用：付款将发送到 test.payu.in，不会扣除真实款项。；当店铺默认货币不是 INR 时，页面会显示错误：此时只有顾客以 INR 付款时，结账才会显示该网关。如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空，也不能超过 128 个字符；Sort Order 必须为整数（允许负数）；Total 必须为大于或等于 0 的数字；地区（geo zone）和订单状态必须存在；否则不会保存任何内容。密钥和 salt 中的空格和换行会被删除，因为粘贴进去的空格会导致每个 PayU 响应的校验失败。如果在未填写当前模式的密钥和 salt 的情况下启用了付款方式，保存后页面会向您发出警告。

PayU India

本部分以一段简短说明开头：银行卡、NetBanking、UPI 和电子钱包在 PayU 托管的付款页面上；只有通过有效的 PayU 签名的结果才会被接受；仅支持卢比。

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

Title：顾客在结账时看到的付款方式标题。它也是订单中保存的付款方式名称。默认：PayU India。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU。

Sort Order：PayU India 在结账付款方式中的位置。留空或输入整数。

Geo Zone：仅对所选地区内的付款地址提供 PayU India。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单在店铺默认货币下必须达到的结账金额，达到后才会提供 PayU India。留空则对任何金额都提供 PayU India。

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 模式下使用。

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

已保存的 salt 不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。要删除已保存的 salt，请勾选字段下方的 Clear the saved salt on save，然后点击 Save。

返回和 Webhook URL

Return URL：在 OpenCart 3 中格式类似 https://your-store/index.php?route=extension/payment/wcp_payu_india_payment/back，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_payu_india_payment/payment/wcp_payu_india_payment.back。每笔付款时它都会自动发送给 PayU；无需进行任何配置。

Webhook URL：在 OpenCart 3 中格式类似 https://your-store/index.php?route=extension/payment/wcp_payu_india_payment/webhook，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_payu_india_payment/payment/wcp_payu_india_payment.webhook。可选，但推荐设置：即使顾客在返回前关闭浏览器，它也能确认付款。请在 PayU Dashboard > Webhooks 中为成功和失败的付款添加它。请完全按照设置页面显示的样子复制 URL。该 URL 必须可以从互联网访问（不能有基本身份验证或防火墙拦截）。店铺的维护模式不会阻止它。

Webhook 携带与顾客返回时相同的已签名结果。没有有效 PayU hash 的 Webhook 会被拒绝。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 PayU 发送了正确签名的结果后，订单才会获得状态。失败或取消的付款会使订单保持无状态，顾客会带着保留的购物车返回结账页面。以下每个字段都列出您的 OpenCart 订单状态。

Order Status After Payment：以 INR 支付的金额与预期一致的成功付款，并在启用 Verify Payment 时经 verify_payment 确认。默认：Processing。

Awaiting PayU Payment Status：PayU 报告付款待处理（UPI collect、NetBanking 进行中）。PayU 确认后，订单会获得付款后的状态。默认：Pending。

On Hold (Review) Status：PayU 报告了一笔需要人工审核的成功付款（参见订单状态）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Payment Error Status：PayU 随后报告为失败的待处理付款。默认：Failed。

Refunded Status：在订单页面中将所有已付款项全部退款后设置。默认：Refunded。

Cancelled Order Status：您的店铺用于已取消订单的状态。为此类订单收到的付款会使其进入审核，而不是标记为已付款。扩展从不设置此状态。默认：Canceled。

高级

Verify Payment：使用 PayU verify_payment API 再次核实每笔成功付款。推荐。如果无法完成核实，订单会进入审核，而不是标记为已付款。默认：开启。

Enable Logging：将网关事件用于故障排除，记录到 OpenCart 日志文件夹（storage/logs）中的 payu_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会记录；此选项会额外记录其他事件，例如每个付款表单和每个 PayU 结果。密钥、salt 和顾客个人数据绝不会被记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。

Delete data on uninstall：卸载扩展时删除网关设置和日志。订单和 PayU 交易记录绝不会被删除。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。salt 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 salt 会被保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 PayU India）。在 Confirm Order 步骤，顾客会看到您的说明；OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。如果订单中没有电话号码，OpenCart 4 的确认区块还会显示 Phone 字段，并附带提示 PayU India 需要付款人的电话号码。 在此输入的号码会发送给 PayU，并保存用于下一次尝试；订单中的电话号码优先。当顾客点击 Confirm Order 时，扩展会检查货币、当前模式的凭据以及订单的电话号码。如果没有电话号码，顾客会停留在该步骤，并显示 PayU India 需要电话号码。请输入您的电话号码后重试。 否则，扩展会为订单总额（INR）生成一个已签名的付款请求，浏览器会立即将其发送到 PayU 托管的付款页面。页面会显示 您将被重定向到 PayU 以完成付款。，并且如果浏览器没有自动继续，还会显示 Pay with PayU 按钮。在 PayU 页面上，顾客可以使用银行卡、NetBanking、UPI 或电子钱包付款。

每次点击 Confirm Order 都会以其自己的 PayU 交易 ID（txnid）开始一次新尝试，该 ID 以订单号开头，并与其金额和模式一起保存。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则更新结账中的订单，因此在那里新的尝试会支付同一订单。在同一订单中较早的、仍然打开的付款页面上完成的付款仍会被接受。如果同一购物车中的另一订单已付款、正在等待 PayU，或处于审核中，顾客会直接进入成功页面，不会创建新的付款表单。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。

PayU 会随顾客一起返回结果，如果已配置，还会通过 Webhook 发送。只有使用发起付款时所在模式的密钥和 salt 生成的有效 PayU hash，并且交易 ID 是为该订单发出的，结果才会被接受。开启 Verify Payment 时，成功的结果还会通过 PayU verify_payment API 进行核实。已付金额必须与该次尝试的金额以及订单总额完全一致，精确到 INR 的小数位（paisa）。只有 PayU 以这种方式确认后，订单才会被标记为已付款，然后以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。扩展会处理以下 PayU 结果：

成功或待处理的付款之后，顾客会看到 OpenCart 订单成功页面。待处理的付款会添加 您的 PayU 付款待处理。PayU 确认结果后，订单将随即更新——无需再次付款。；处于审核中的订单会添加 您的付款正在审核中。如有其他需要，我们会与您联系。；处于付款错误或已取消状态且未付款的订单，则会显示 您的 PayU 付款未完成。请就此订单与我们联系。

付款未成功后，顾客会带着以下消息返回结账页面：付款未完成。请重试或选择其他付款方式。、付款已取消。您可以重试。，或者在无法核实结果时显示 我们无法确认付款结果。如果您的账户已被扣款，请在再次付款前与我们联系。 如果顾客返回时结果仍在处理中，页面会显示 我们正在确认您的 PayU 付款。如果您已完成付款，订单将很快更新——请勿重复付款。，并带有 Check again 和 Back to checkout 按钮。在 OpenCart 4 中，这些消息显示在结账页面上方。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即被关闭（例如其待处理付款失败，或您取消了它），顾客会被送回结账页面，并显示消息 您之前的订单已取消或付款失败。请重新确认订单。 如果该订单已付款，之后被取消或被商店退款，消息为 您之前的订单已被取消或被商店退款。请重新确认订单，以新订单付款。 如果该订单此前已为较早的购物车付款，而购物车之后发生了变化，消息为 您之前的订单已付款。购物车已变化——请重新确认订单，以为当前购物车付款。 下一次 Confirm Order 将为新订单付款。已关闭的订单绝不会显示为已付款。

当店铺处于维护模式时，Webhook 仍然有效，因为 OpenCart 会放行付款扩展的请求（在 OpenCart 4 中，扩展会为此添加自己的启动动作，该动作同时允许顾客从 PayU 返回）。

该扩展仅以 INR 收款，不支持多货币处理（MCP）。它不支持保存银行卡或令牌化、订阅、站内（seamless）银行卡表单、EMI 或优惠管理，也不支持 PayU 一键结账。

订单与退款

订单状态

无状态（缺失订单）：顾客已被发送到 PayU 但尚未付款，或付款失败或被取消。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设为 Missing Orders 时显示。

Order Status After Payment（默认 Processing）：付款已确认。备注显示 PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU Payment Status（默认 Pending）：UPI 或 NetBanking 付款仍在 PayU 处于待处理状态。PayU 确认后，订单会获得已付款状态。

On Hold (Review) Status（默认 Pending）：已付金额或币种与订单不符，verify_payment API 无法访问或尚未确认付款，或收到了处于 Cancelled Order Status 的订单的付款。备注会说明原因。请在 PayU Dashboard 中核对交易，然后设置已付款状态，或者取消订单并对付款进行退款。如果只是核实失败，则在下一次结果送达时订单会自动标记为已付款。

Payment Error Status（默认 Failed）：待处理的付款之后被拒绝或取消。之后的成功结果仍会使订单付款。

Refunded Status（默认 Refunded）：所有已付款项已通过扩展退款。

如果 PayU 报告同一已付款订单又有一笔成功付款，订单不会改变，备注会要求您在 PayU Dashboard 中对重复付款进行退款。对于同一购物车中另一已付款订单的付款，该订单会保持无状态，并在已付款订单上添加备注。对于已切换到其他付款方式的订单，PayU 付款只会添加备注。

备注是订单 History 中的条目，顾客看不到。

VibeFox PayU India Payment Gateway 选项卡

在 Sales > Orders 中打开一笔通过 PayU India 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox PayU India Payment Gateway 选项卡会显示 PayU transaction ID (mihpayid)、Store transaction ID (txnid)、Environment（测试付款会带有 Test mode 标记）、PayU Status、付款的 Mode / bank、Paid / refund requested (INR) 金额、退款表单、退款历史以及订单的 PayU notes。对于处于审核中的订单，它会显示提醒您核对付款。该选项卡对有权访问扩展的用户显示。

退款

在 VibeFox PayU India Payment Gateway 选项卡中输入 Amount（自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via PayU。确认提问 Refund this amount through PayU? This cannot be undone. 支持全额和部分退款；金额必须大于零，且不能超过 PayU 已收取金额的剩余可退部分。您需要修改扩展的权限（在 System > Users > User Groups 中设置）。退款通过 PayU 退款 API 发送，使用付款所用模式的密钥和 salt，因此这些凭据必须已设置。同一订单同一时间只会运行一个 PayU 请求。如果 PayU 拒绝退款，选项卡会显示 PayU refund failed: 以及 PayU 的消息，且不会记录任何退款。

PayU 会将退款排队并异步完成；顾客通常会在 5–7 个工作日内收到款项。退款历史和备注会显示金额、PayU 请求 ID 和原因。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。退款在 PayU 报告付款的交易 ID 后即可使用。扩展不会稍后再检查退款状态。

Sales > Returns 中的商品退货不会通过 PayU 退款。在 PayU Dashboard 中进行的退款不会同步回 OpenCart。

许可证密钥

该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayU India Payment Gateway 是 Extensions > Extensions > Payments > VibeFox PayU India Payment Gateway > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示被遮盖的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: opencart-payment-payu-india 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。区块中的文字遵循后台语言（包括英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。店铺地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 PayU India。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标注 (unlicensed — visible to admins only)，这样您就可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 中此预览不可用：店铺看不到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。

许可证过期时，扩展仍会继续工作，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。

故障排除

结账时不显示 PayU India：检查许可证是否有效，Enable/Disable 是否开启，以及所选 Mode 的密钥和 salt 是否已填写。检查顾客是否以 INR 付款，付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。当凭据缺失或店铺货币不是 INR 时，设置页面会显示警告。

付款已成功，但订单仍无状态：顾客没有返回店铺，也没有收到 Webhook。请在 PayU Dashboard > Webhooks 中为成功和失败的付款添加设置页面中的 Webhook URL，并确保它可以从互联网访问。

Webhook 返回 invalid_signature：PayU hash 不匹配。请检查付款所用模式的密钥和 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 需要电话号码：订单没有电话号码。请在结账中保留 Telephone 字段。在 OpenCart 4 中，顾客可以在确认区块的 Phone 字段中输入号码。

顾客看到 This payment method is not available. Please reload the checkout page.：付款方式在此期间已被关闭、凭据缺失，或结账已与订单不匹配。顾客需要重新加载结账页面。

订单处于审核状态：阅读 VibeFox PayU India Payment Gateway 选项卡中的备注。原因可能是金额或币种不符、核实失败或待处理，或是已取消订单的付款。

退款失败：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 结果。

对开发者：在付款请求签名之前，扩展会触发 OpenCart 事件 payu_p_request_fields，并附带请求字段和订单。密钥、交易 ID、金额和返回 URL 无法通过该事件修改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayU India Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中同时删除其事件以及在维护模式下允许 Webhook 和顾客返回的启动动作）。如果 Delete data on uninstall 已开启，其余网关设置（标题、说明、模式、密钥、salt、付款验证、日志记录）和日志会被删除；如果关闭，它们会保留，以便之后重新安装。PayU 交易记录和退款请求始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PayU India Payment Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

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