VibeFox PayU for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并启用 cURL 扩展。

货币：顾客的结账货币必须是以下之一：PLN、EUR、CZK、HUF、RON、BGN、GBP、USD、CHF、DKK、NOK、SEK、UAH。该货币还必须在您在 PayU 的收款点中启用。对于其他货币，结账时不会显示该付款方式。

店铺的互联网访问：PayU 会向您的店铺发送付款通知，因此店铺必须可以从互联网访问（不能受 HTTP 身份验证保护，也不能被防火墙拦截）。没有通知时，顾客从 PayU 返回后仍会检查付款。

PayU 账户：您需要收款点（POS）的四个密钥：POS ID、Second key (MD5)、OAuth client_id 和 OAuth client_secret。它们位于 PayU 商户后台的 Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys 中。沙盒密钥来自单独的 PayU 沙盒账户。

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

安装

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

OpenCart 3

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

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

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

4. 输入四个 Sandbox 密钥和四个 Live 密钥（参见配置）。无需在 PayU 中配置通知 URL。

5. 开启 Enable/Disable 并点击 Save。在完成一次测试付款之前，请保持 Test Mode 开启；之后关闭它，即可使用 Live 密钥接收真实付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3–5 步输入许可证密钥和 PayU 密钥。设置页面及其字段在两个版本中相同。仅通知 URL 不同（参见「付款通知」）。

新安装默认关闭付款方式，并开启测试模式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox PayU Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当沙盒模式开启时（沙盒（测试）模式已开启：付款将发送到 PayU 沙盒，不会扣除真实款项。请勿发货在测试模式下付款的订单。），当当前模式的四个密钥之一缺失时（此时结账页面不会显示 PayU），以及当 PayU 不接受店铺默认货币时（此时 PayU 会对该货币的订单隐藏），页面都会向您发出警告。如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，所有密钥中的空格和换行都会被删除，因为从 PayU 后台复制时常会带入这些字符。Title 不能为空，也不能超过 128 个字符（页面会显示 请输入付款方式名称（最多 128 个字符）。）；Sort Order 必须为整数（允许负数）；Total 必须为大于或等于 0 的数字；地区（geo zone）和订单状态必须存在。否则不会保存任何内容。保存设置还会清除缓存的 PayU 访问令牌。

PayU

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

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

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely via PayU。

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

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

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

API 凭据

在 PayU 商户后台中找到密钥：Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys。沙盒密钥来自单独的 PayU 沙盒账户。某一模式的四个密钥必须全部填写。该部分包含 PayU 开发者文档的链接。

Test Mode：使用 PayU 沙盒和下方的 Sandbox 密钥。不会扣除真实款项。开启时，顾客在 Confirm Order 步骤会看到 沙盒模式：不会收取真实付款。。关闭它即可使用 Live 密钥接收真实付款。默认：开启。

Live POS ID：您正式环境收款点的 POS ID（merchantPosId）。

Live Second Key (MD5)：用于验证 PayU 付款通知的签名。

Live OAuth Client ID：收款点的 OAuth client_id。

Live OAuth Client Secret：收款点的 OAuth client_secret。

Sandbox POS ID：您 PayU 沙盒收款点的 POS ID。

Sandbox Second Key (MD5)：用于验证 PayU 沙盒付款通知的签名。

Sandbox OAuth Client ID：沙盒收款点的 OAuth client_id。

Sandbox OAuth Client Secret：沙盒收款点的 OAuth client_secret。

已保存的 Second Key 和 client secret 不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。POS ID 和 client ID 按保存时的样子显示。

Clear saved secrets：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。

每笔付款都会记住其所用环境。通知、状态查询、付款的接收或取消以及退款始终使用该环境的密钥，因此切换模式后，旧付款仍可正常处理。使用沙盒密钥签名的通知绝不会用于真实付款，反之亦然。

订单状态

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 PayU 通过已签名的通知，或在顾客返回时通过状态查询确认付款后，订单才会获得状态。OpenCart 没有 On hold 状态：等待类状态默认为 Pending，订单的 PayU 选项卡及其备注会说明原因。以下每个字段都列出您的 OpenCart 订单状态；您可以在 System > Localisation > Order Statuses 中创建自己的状态。

Order Status After Payment：当 PayU 确认付款（COMPLETED）且金额和币种一致时设置。默认：Processing。

Awaiting PayU Payment Confirmation：付款已授权，等待接收（自动接收已关闭或失败）。在订单的 PayU 选项卡中使用 Receive PayU payment 或 Cancel PayU payment。默认：Pending。

PayU Payment On Hold：已付金额或币种与订单不符，或者为已取消的订单完成了付款。订单不会标记为已付款；备注会说明原因。默认：Pending。

Payment Error Status：等待确认的订单的付款已被取消或拒绝。默认：Failed。

Cancelled Order Status：对处于此状态的订单完成的 PayU 付款会将订单置为等待，而不是悄悄重新打开。扩展从不设置此状态。默认：Canceled。

Refunded Status：在订单的 PayU 选项卡中将付款全额退款后设置。默认：Refunded。

付款通知

Notification URL：显示 PayU 发送通知的地址。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_payu_payment/notify，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_payu_payment/payment/wcp_payu_payment.notify，由您 OpenCart 安装的店铺前台地址生成。扩展会在每笔付款时将其发送给 PayU，因此无需在 PayU 后台进行任何配置。请确保它可以从互联网访问（不被防火墙或 HTTP 身份验证拦截）。店铺处于维护模式时通知也能正常工作（在 OpenCart 4 中，通过扩展的启动动作实现，该动作同时允许顾客从 PayU 返回）。没有有效签名的通知会被拒绝。

高级

Receive payments automatically：自动接收等待确认的付款。仅当您在 PayU 后台中为收款点关闭了自动接收时，此项才有意义：此时付款会等待确认（WAITING_FOR_CONFIRMATION）。开启此选项后，扩展会立即接收这些付款，并在 PayU 报告付款已完成时，使订单获得已付款状态。关闭此选项或接收失败时，订单会获得 Awaiting PayU Payment Confirmation，您可以在订单的 PayU 选项卡中用按钮接收或取消付款。默认：开启。

Logging：将技术事件（订单号、PayU 订单 ID、状态、错误；不含密钥或个人数据）写入 OpenCart 日志文件夹（storage/logs）中的 wc_pu_debug.log.php。该文件无法通过网页打开。错误始终会记录；其他事件仅在此选项开启时记录。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。订单及其付款数据（PayU 交易和退款）绝不会被删除。缓存的 PayU 访问令牌始终会被删除。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 PayU）。在 Confirm Order 步骤，顾客会看到您的说明以及提示 您将被重定向到 PayU 以完成付款（BLIK、银行转账、银行卡及其他方式）。 OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会以订单货币创建一笔金额为订单总额的 PayU 订单，描述为 Order #、订单号和您的店铺名称，并附上商品、配送方式以及订单的其他总计行，以便在 PayU 页面上显示。顾客的电子邮件、姓名和电话会传递给 PayU，PayU 页面的语言跟随店铺前台语言。顾客会被带到 PayU 页面，在那里选择付款方式并付款。

每次尝试都会获得自己的 PayU 订单。当顾客再次尝试时（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则更新结账中的订单），同一订单和同一购物车之前尝试中未完成的 PayU 付款会在 PayU 处被取消，因此旧的付款链接不能被支付两次。如果发现之前的付款实际已经支付，则会改为采用该付款；而已经付款、处于等待或等待确认状态的订单或购物车，会直接进入成功页面，不会再次付款。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。

顾客仅返回您的店铺绝不会支付订单。只有在 PayU 确认后，订单才会被标记为已付款：通过使用该付款所在环境的 Second Key 签名的通知，或在顾客返回时在服务器上对 PayU 订单进行状态查询（每笔付款至多每 10 秒一次）。金额和币种必须一致。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。扩展会处理以下 PayU 状态：

付款确认后，顾客会看到 OpenCart 订单成功页面。对于等待确认或处于等待状态的订单，页面会额外显示 您的付款正在核实中。确认后我们会向您发送电子邮件。 之后如果此类订单付款成功或付款失败，OpenCart 会将新状态通知顾客。如果订单付款失败，页面会显示 您的 PayU 付款未完成。请就此订单与我们联系。

如果顾客返回时 PayU 尚未确认付款，Payment confirmation 页面会显示 我们尚未收到 PayU 的付款确认。如果付款中断，您可以重试：（或者，当 PayU 报告错误时，显示 付款未完成。您可以重试：），并带有 Pay again（返回结账）和 Check again 按钮。通知一到达就会设置订单状态。如果付款已取消，顾客会返回结账页面，并显示 付款未完成。您可以重试或选择其他付款方式。 购物车会被保留。在 OpenCart 4 中，此消息显示在结账页面上方。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间被关闭（例如其等待确认的付款已取消，或您取消或退款了该订单），顾客会被送回结账页面，并显示消息 您之前的订单已关闭（未付款、已取消或已退款）。请重新确认订单，以新订单付款。 当顾客从 PayU 返回到一个未付款即被关闭的订单时，消息为 付款未完成。您可以重试或选择其他付款方式。 如果该订单此前已为较早的购物车付款，而购物车之后发生了变化，顾客会被带回结账页面。无论哪种情况，下一次 Confirm Order 都会为当前购物车的新订单付款。已关闭的订单绝不会显示为已付款。

如果 PayU 无法启动付款，顾客会停留在 Confirm Order 步骤，并显示 付款错误。请重试或选择其他付款方式。 技术原因会写入日志。如果当前模式的密钥缺失，消息为 付款网关配置不正确。请联系管理员。

顾客在 PayU 页面而非您的结账页面中选择付款方式。该扩展不会在您的网站上提供银行卡表单，不支持保存银行卡或一键支付、订阅，也不提供 PayU 分期或信贷组件。它为每个环境使用一个收款点。

订单与退款

订单状态

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

Order Status After Payment（默认 Processing）：付款已确认。备注会显示 PayU 订单 ID、金额和环境（沙盒或正式）。

Awaiting PayU Payment Confirmation（默认 Pending）：付款已授权，等待您处理（自动接收已关闭，或接收失败）。

PayU Payment On Hold（默认 Pending）：已付金额或币种与订单不符，等待确认的付款金额不同，或为已取消的订单完成了付款。备注会说明具体情况。请检查订单并完成发货，或对付款进行退款。

Payment Error Status（默认 Failed）：等待确认的订单的付款已被取消或拒绝。

Refunded Status（默认 Refunded）：付款已通过扩展全额退款。

每条通知只处理一次：重复的通知不会添加备注，也不会再次修改订单。如果对已付款或已退款的订单，或对已付款购物车中的另一订单完成了另一笔付款，已付款订单上的备注会提示您在 PayU 后台中退款。对于已付款或已关闭订单上等待确认的付款，将自动取消，以免重复扣款。

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

VibeFox PayU Payment 选项卡

在 Sales > Orders 中打开一笔通过 PayU 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox PayU Payment 选项卡会显示 PayU order ID（沙盒付款会带有 Sandbox 标签）、extOrderId、PayU status、Payment amount、Paid / refunded 金额、退款表单、Refunds 历史、订单的 PayU payment attempts 以及 PayU notes。该选项卡对有权访问扩展的用户显示；其操作需要修改扩展的权限（在 System > Users > User Groups 中设置）。

等待确认的付款

对于有等待确认付款的订单，选项卡会显示 Receive PayU payment 和 Cancel PayU payment。确认提问后，该操作会使用付款所在环境的密钥发送给 PayU，并附带您的用户名添加到备注中，新的 PayU 状态会立即生效：已接收的付款会设置 Order Status After Payment，已取消的付款会设置 Payment Error Status。

退款

在选项卡中输入 Amount（自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via PayU。确认提问 Refund this amount through PayU? This cannot be undone. 支持全额和部分退款。PayU 完成付款后即可退款。退款会针对实际付款的 PayU 订单，使用付款所在环境的密钥发送，因此这些密钥必须已设置。退款以 PayU 实际扣款的金额和币种进行；因此在金额或币种不一致后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款原因将作为退款说明发送。如果 PayU 拒绝退款，选项卡会显示 PayU 的错误，且不会记录任何退款。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会将商品退回库存。部分退款不会更改状态。

PayU 的退款是异步处理的。扩展会立即添加一条包含 PayU 退款 ID 和状态的备注；最终状态稍后通过 PayU 通知到达，并添加到备注和退款历史中。如果 PayU 取消了退款，备注会说明款项未退还给顾客，且该金额可以再次退款。

Sales > Returns 中的商品退货不会通过 PayU 退款。

许可证密钥

该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayU Payment 是 Extensions > Extensions > Payments > VibeFox PayU Payment > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示被遮盖的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: opencart-payment-payu 一行，以及 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。如果仍然发起了付款，顾客会看到 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：检查许可证是否有效，Enable/Disable 是否开启，以及当前模式的四个密钥是否都已填写：沙盒模式填写 Sandbox 密钥，正式模式填写 Live 密钥。检查顾客的货币是否属于支持的货币之一，付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。当密钥缺失或店铺货币不受支持时，设置页面会显示警告。

付款已成功，但订单仍无状态：PayU 尚未送达通知，返回页面的状态查询也没有发现已完成的付款。请检查设置中显示的通知 URL 是否可以从互联网访问。开启 Logging 查看收到的内容。顾客也可以在 Payment confirmation 页面点击 Check again。

通知返回 Invalid signature：该通知没有使用两个环境中任一环境的 Second Key 签名。请检查 Live Second Key (MD5) 和 Sandbox Second Key (MD5)。回复 Invalid signature for this payment 表示通知是用与付款环境不同的环境密钥签名的。

通知返回 Ignored: unknown PayU order：该 PayU 订单不是由本店铺创建的，例如同一收款点上的另一家店铺。PayU 将停止重试。

通知返回 Busy, retry later：该购物车在同一时刻正被另一个请求确认。PayU 会重复发送通知。开启 Logging 查看原因。

在浏览器中打开通知 URL 显示 POST expected：这是正常的。该 URL 只接受来自 PayU 的通知。

顾客在 Confirm Order 后看到 Payment error：开启 Logging，并查看扩展页面上的 Log 字段。日志会显示 HTTP 代码和 PayU 状态。Could not authenticate with PayU (check the OAuth client ID / secret). 表示当前模式的 OAuth 密钥错误。This payment method is not available. 表示结账会话已与订单不匹配，或者付款方式在此期间被关闭：顾客需要重新加载结账页面。

订单处于 PayU Payment On Hold：阅读 VibeFox PayU Payment 选项卡中的备注（参见订单状态），然后完成订单或对付款进行退款。

订单处于 Awaiting PayU Payment Confirmation：您的收款点已关闭自动接收，付款正等待您处理。请在选项卡中使用 Receive PayU payment 或 Cancel PayU payment。

退款失败或没有退款表单：选项卡会说明原因。Refunds are available once PayU has completed the payment. 表示 PayU 尚未完成该订单的付款。提示缺少 Sandbox 或 Live 密钥，表示付款是在该环境中进行的，但该环境的密钥尚未设置。请输入这些密钥后重试。没有修改扩展的权限时，选项卡会显示 You do not have permission to refund (modify this extension).

卸载

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

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

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