VibeFox PayU LATAM for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：顾客的结账货币必须为 ARS、BRL、CLP、COP、MXN、PEN 或 USD，即 PayU Latam 在阿根廷、巴西、智利、哥伦比亚、墨西哥、巴拿马和秘鲁处理的货币。使用其他货币时，结账页面不会显示该付款方式。

PayU Latam 账户：您需要 PayU 商户账户中的三个值：商户 ID（merchant ID）、您销售所在国家的账户 ID（account ID）以及 API 密钥。它们位于 PayU 商户面板中的 Settings > Technical configuration（merchant ID、API key）和 Accounts（account ID）下。测试时，PayU 会在其开发者文档的「Test your solution」页面公布公开的沙盒凭据和测试卡。由于付款在 PayU 托管页面上完成，且本扩展从不调用 PayU API，因此无需 API Login 和其他 API 凭据。

店铺的互联网访问：PayU 从其服务器将付款结果发送到您的店铺，因此店铺必须可从互联网访问（不能是本地站点，也不能设置密码保护）。

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

安装

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

OpenCart 3

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

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

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

4. 输入沙盒凭据和正式凭据（参见配置）。无需在 PayU 中配置任何确认 URL。

5. 开启 Enable/Disable 并点击 Save。在完成一次测试付款之前，保持 Sandbox 开启；之后关闭它，即可使用正式凭据接受真实付款。

OpenCart 4

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

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

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

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

新安装时，付款方式默认关闭，沙盒默认开启。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit。各部分列在左侧；列表下方的 Save 按钮保存整个页面。在设置上方，页面会显示 Sandbox mode. Payments go to the PayU sandbox and no real money is charged.（沙盒开启期间）；当当前环境的商户 ID、账户 ID 或 API 密钥缺失时显示错误（此时结账页面不提供 PayU Latam）；当 PayU Latam 不处理店铺默认货币时显示警告。若没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空，且不能超过 128 个字符（页面会显示 Enter a title for the payment method (at most 128 characters).）；Sort Order 必须是整数（允许负数）；Total 必须是大于或等于 0 的数字；地理区域和订单状态必须存在。否则不会保存任何内容。凭据首尾的空格会被忽略。

PayU LATAM

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

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

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

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

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

Total：订单必须达到的结账总额（以店铺默认货币计）才会提供 PayU LATAM。留空则对任何金额都提供 PayU LATAM。

环境

Sandbox：付款使用沙盒凭据发送到 PayU 沙盒，不会收取真实款项。关闭时，使用正式凭据和 PayU 正式结账页面。默认：开启。开启期间，顾客在 Confirm Order 步骤会看到 Sandbox mode: no real money is charged.

正式凭据

在 PayU 商户面板中查找：Settings > Technical configuration（merchant ID、API key）和 Accounts（您销售所在国家的 account ID）。本节提供指向 PayU 商户面板的链接。

Merchant ID：您的 PayU 商户账户的数字标识符。

Account ID：PayU 账户的标识符。每个国家一个账户。

API Key：用于签署付款和验证 PayU 通知的密钥。

沙盒凭据

PayU 为其沙盒公布公开的测试凭据和测试卡。本节提供指向 PayU 文档中「Test your solution」页面的链接。

Sandbox merchant ID：PayU 沙盒的商户 ID。

Sandbox account ID：PayU 沙盒的账户 ID。

Sandbox API key：PayU 沙盒的 API 密钥。

已保存的 API 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear saved secret on save，然后点击 Save。

每次付款尝试都会记住其所在环境。沙盒付款的确认使用沙盒 API 密钥和商户 ID 进行验证，正式付款的确认则使用正式值进行验证，因此切换环境后，待处理的付款仍能正常运作。沙盒付款会在订单备注中标记为沙盒。

确认 URL

本节显示 PayU 报告每个付款结果的 URL。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation，由您 OpenCart 安装的前台地址生成。扩展会在每次付款时将该 URL 发送给 PayU，因此无需在 PayU 中进行任何配置。该 URL 必须可从互联网访问。店铺处于维护模式时它同样有效（在 OpenCart 4 中，通过扩展的启动动作实现，该动作同时允许顾客从 PayU 返回）。确认信息由 PayU 使用您的 API 密钥签名。签名无效、商户 ID 不同或付款参考号并非本店铺发出的确认会被拒绝。扩展会处理以下 PayU 交易状态：

其他状态仅作为备注添加。没有确认，订单就不会获得任何状态。

订单

OpenCart 在 Confirm Order 步骤中创建订单时不带状态（即缺失订单）。只有在收到经签名的 PayU 确认后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款已获批准（PayU 状态 4），且金额和货币符合预期。默认：Processing。

Awaiting Payment Status：待付款（状态 7、10、12、14、15、18，例如尚未完成的现金或银行付款）。当 PayU 确认后，订单会获得 Order Status After Payment。默认：Pending。

On Hold (Review) Status：PayU 批准了付款，但金额或货币与订单不同，或者订单已被取消。备注会显示详细信息；订单不会被标记为已付款。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Failed Payment Status：最近一次尝试的待付款，之后被 PayU 报告为被拒绝、已过期或失败。默认：Failed。

Cancelled Order Status：您的店铺用于已取消订单的状态。对此类订单批准的付款会将其置于 On Hold (Review) Status，而不是标记为已付款。扩展从不设置此状态。默认：Canceled。

高级

Debug log：将付款请求和 PayU 通知记录到 OpenCart 日志文件夹（storage/logs）中的 payu_lp_debug.log.php。该文件无法通过网页打开，当其达到 5 MB 时会被移动到 payu_lp_debug.old.log.php。密钥和个人数据不会被记录。错误和被拒绝的通知始终会被记录，即使此开关关闭。默认：关闭。

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

Delete data：开启时，卸载扩展会删除网关设置和日志。订单和 PayU 付款记录（付款尝试）永远不会被删除。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 PayU LATAM）。在 Confirm Order 步骤中，顾客会看到您的说明；OpenCart 在此步骤创建订单，但仍无状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会准备一个经签名的付款表单，页面显示 You are being redirected to PayU LATAM to complete the payment...，并自动将表单提交到 PayU WebCheckout 页面。如果没有自动跳转，顾客可点击 Pay with PayU LATAM。

表单包含以订单货币计的订单总额、订单的税费和税基（对于不含税的订单，两者均为 0，以免 PayU 添加默认增值税）、带有订单号和店铺名称的描述 Order #，以及顾客的电子邮件、姓名、电话和账单地址。PayU 页面会根据顾客的语言以西班牙语、葡萄牙语或英语打开。在 PayU 页面上，顾客可使用 PayU 账户中启用的任何方式付款。

每次点击 Confirm Order 都会以其自有参考号（OC、订单号和时间戳）开始一次新的付款尝试。在 OpenCart 4 中，新的尝试会支付同一订单。之前的尝试会被记住：如果顾客在较早的 PayU 标签页中付款，该付款仍会被识别。

只有在 PayU 通过经签名的确认信息确认付款后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单电子邮件、更新库存。从 PayU 返回的顾客不会将订单标记为已付款。顾客返回时：

OpenCart 4 中的结账消息显示在结账页面上方。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则更新结账中的订单，但同一购物车只会付款一次：如果同一购物车的另一订单已付款、待付款或审核中，Confirm Order 会直接进入成功页面。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。如果当前环境的凭据缺失，顾客会看到 PayU LATAM is not available right now. Please choose another payment method.

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

本扩展在您的网站上没有付款表单，无法从 OpenCart 退款，不支持保存银行卡、订阅以及分期设置（PayU 在其页面上显示分期）。它不会查询 PayU API 获取付款状态：只有经签名的确认才会更新订单。

订单

订单状态

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

Order Status After Payment（默认 Processing）：PayU 已确认付款，且金额和货币一致。备注会显示交易、金额、付款方式，以及是否为沙盒付款。

Awaiting Payment Status（默认 Pending）：PayU 将付款报告为待处理（现金或银行付款）。当 PayU 确认付款时，订单会转为 Order Status After Payment；如果付款失败，则转为 Failed Payment Status。OpenCart 会就这些变化通知顾客。

On Hold (Review) Status（默认 Pending）：已付金额或货币与订单总额不符，或订单已取消却收到了付款批准。备注会说明具体情况：请在 PayU 商户面板中核对付款，然后处理订单、恢复订单或退款。

Failed Payment Status（默认 Failed）：最近一次尝试的待付款之后被拒绝、过期或以错误结束。备注会显示 PayU 的消息。对较早尝试的拒绝，或对已有已批准付款的订单的拒绝，只会作为备注添加。

每个通知都会在购物车级别的锁定下处理一次：重复的 PayU 通知不会两次更改订单，也不会重复添加备注。已付款的订单绝不会被降级。如果对已付款订单或同一购物车中另一订单又收到了一笔已批准的付款，已付款订单上会有备注说明此情况：如果顾客重复付款，请在 PayU 商户面板中退还重复的款项。

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

VibeFox PayU LATAM Payment 标签页

在 Sales > Orders 中打开一个通过 PayU LATAM 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox PayU LATAM Payment 标签页会显示 Reference、Transaction ID、PayU reference、Status 以及 PayU 状态、Requested 金额、Amount reported by PayU、Payment method、PayU message、沙盒付款的 SANDBOX 标记、该购物车的全部 Payment attempts 列表，以及该订单的 PayU LATAM notes。该标签页会显示给有权访问本扩展的用户。

退款

退款不能通过 OpenCart 进行。请在 PayU 商户面板中退还该交易，然后在 OpenCart 中手动记录退款。

许可证密钥

本扩展需要配合 vibefox.net 提供的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox PayU LATAM Payment 是 Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-payment-payu-latam 一行和 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 LATAM 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已发起的付款仍会通过 PayU 确认和顾客返回来完成确认。

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

故障排除

PayU LATAM 没有出现在结账页面：请检查许可证是否有效，Enable/Disable 是否开启，以及当前环境的商户 ID、账户 ID 和 API 密钥是否已填写：Sandbox 开启时使用沙盒凭据，关闭时使用正式凭据。同时检查顾客的货币是否为 ARS、BRL、CLP、COP、MXN、PEN 或 USD，付款地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：PayU 确认未能到达您的店铺，或被拒绝。请检查设置中显示的确认 URL 是否可从互联网访问（不能是本地站点，也不能有防火墙或密码保护）。查看扩展页面中的 Log 字段，找出被拒绝的确认。PayU 会在任何错误响应之后重新发送确认。

确认返回 Invalid signature：确认信息未使用付款所在环境的 API 密钥签名。正式付款请检查 API Key，沙盒付款请检查 Sandbox API key。

确认返回 Merchant mismatch：确认信息中的商户 ID 与付款所在环境的 Merchant ID 或 Sandbox merchant ID 不符。请输入处理付款的 PayU 账户的商户 ID。

确认返回 Gateway not configured：付款所在环境的 API 密钥或商户 ID 缺失，例如在沙盒付款待处理期间删除了沙盒凭据。请重新输入；PayU 会重试确认。

确认返回 Retry：购物车在同一时刻正被另一个请求处理，或无法设置订单状态。PayU 会再次发送确认。请查看 Log 了解原因。

确认返回 Unknown reference：该付款参考号不是由本店铺发出的。

确认 URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 PayU 的请求。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不匹配，或者 Enable/Disable 在此期间被关闭。顾客需要重新加载结账页面。

订单处于审核状态：请阅读 VibeFox PayU LATAM Payment 标签页中的备注。已付金额或货币与订单不一致，或者付款在订单被取消后才到达。请在 PayU 商户面板中核对该交易。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayU LATAM Payment 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中同时删除其事件以及在维护模式下允许确认和顾客返回的启动动作）。如果 Delete data 已开启，其余网关设置（标题、说明、沙盒、凭据、调试日志开关）和日志也会被删除；如果关闭，则会保留，以便日后重新安装时使用。付款尝试始终会保留，因此即使重新安装后，PayU 对旧尝试的延迟确认仍会被识别。已有订单会保留其付款备注。

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

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