VibeFox Wompi for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：哥伦比亚比索（COP）。Wompi Colombia 以 COP 收费。如果您的商店尚未添加 COP，请在 System > Localisation > Currencies 中添加；仅当顾客以 COP 结账时才会提供该付款方式。如果商店的默认货币不是 COP，设置页面会向您发出警告。

Wompi 账户：Wompi Colombia 商户账户。每个环境（沙盒和生产）都有四个密钥：公钥、私钥、事件密钥和完整性密钥。您可以在 Wompi 商户后台（comercios.wompi.co）的开发者部分找到它们。Wompi El Salvador 和 Panama 使用不同的 API，不受支持。

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

安装

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

OpenCart 3

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

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

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

4. 从 Wompi 商户后台粘贴沙盒和生产环境的密钥，并在 Wompi 中设置 Events URL（参见“配置”）。

5. 开启 Enable/Disable 并点击 Save。在沙盒模式下测试一次付款，然后关闭 Sandbox mode，即可接受真实付款。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_wompi_payment.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、Wompi 密钥和 Events URL。两个版本的设置页面及其字段相同。只有 Events URL 不同（参见 Events URL）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Wompi Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，状态框会显示当前模式，即 SANDBOX 或 PRODUCTION。如果缺少此模式的某个密钥，状态框会列出该密钥，并说明在该环境的所有密钥设置完成之前，结账时将隐藏付款方式。所有密钥设置完成后，状态框会显示是否将收取真实付款。保存时，如果某个密钥的前缀与其所在部分不符，或者 Wompi 已启用但因缺少密钥而在结账时隐藏，扩展会向您发出警告。Title 长度不得超过 128 个字符（Title must be at most 128 characters.），Sort Order 必须为整数（Sort Order must be a whole number.），Total 必须为大于或等于 0 的数字（Total: enter a number, 0 or greater.），所选的地区和订单状态也必须存在；否则不会保存任何内容，页面会显示错误。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

Wompi

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

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Wompi。最多 128 个字符。如果留空，则使用扩展名称。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Sort Order：Wompi 在结账付款方式中的位置。可以留空或输入整数；允许负数。

Geo Zone：仅对所选地区内的付款地址提供 Wompi。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，如果结账时没有付款地址，则会检查配送地址。

Total：订单在商店默认货币下须达到的结账总额，达到后才提供 Wompi：数字，0 或更大。留空则对任何总额都提供。Wompi 本身要求至少 COP 1,500。

Wompi 账户

请从 Wompi 商户后台（comercios.wompi.co）的开发者部分复制密钥。每个环境都有自己的公钥、私钥、事件密钥和完整性密钥。

Sandbox mode：使用 Wompi 沙盒（沙盒密钥，不产生真实费用）。它会同时切换密钥和 Wompi API（sandbox.wompi.co 或 production.wompi.co）。付款尝试会保留其发起时所在的环境。默认：开启。关闭则接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Sandbox mode: no real payment is made.

沙盒密钥

Wompi 沙盒的四个密钥。它们分别以 pub_test_、prv_test_、test_events_ 和 test_integrity_ 开头。

Public key：沙盒公钥（pub_test_...）。它在 Wompi Web Checkout 中标识您的账户。

Private key：沙盒私钥（prv_test_...）。用于从 Wompi API 读取交易。

Events secret：沙盒事件密钥（test_events_...）。用于验证 Wompi 事件的签名。

Integrity secret：沙盒完整性密钥（test_integrity_...）。用于对发送到 Web Checkout 的付款请求签名。

生产环境密钥

Wompi 生产环境的四个密钥。它们分别以 pub_prod_、prv_prod_、prod_events_ 和 prod_integrity_ 开头。

Public key：生产公钥（pub_prod_...）。

Private key：生产私钥（prv_prod_...）。

Events secret：生产事件密钥（prod_events_...）。

Integrity secret：生产完整性密钥（prod_integrity_...）。

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

Events URL（webhook）

Wompi 事件会告知您的商店某笔交易已发生变化。在 Wompi 商户后台的开发者部分，为沙盒和生产环境分别设置本部分显示的 Events URL。该地址由您的 OpenCart 安装的商店地址生成，在 OpenCart 3 中格式类似于 https://your-store/index.php?route=extension/payment/wcp_wompi_payment/webhook，在 OpenCart 4 中则类似于 https://your-store/index.php?route=extension/wcp_wompi_payment/payment/wcp_wompi_payment.webhook。请完全按照设置中显示的样子复制该 URL。

该扩展使用以下事件：

其他事件将返回 Ignored。每个事件都会使用其所在环境（沙盒或生产）的事件密钥进行校验。没有有效签名的 webhook 会被拒绝。校验之后，会使用该环境的私钥从 Wompi API 读取交易，并且只使用这些数据。如果没有 Events URL，订单只有在顾客付款后返回商店时才会获得状态。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。只有当 Wompi 报告交易后，订单才会获得状态。下方每个字段都会列出您的 OpenCart 订单状态。

Order Status After Payment：以 COP 计、金额符合预期的 APPROVED 交易。默认：Processing。

Awaiting Payment Status：PENDING 交易，例如等待确认的 PSE、Nequi 或现金付款。当 Wompi 批准后，订单会获得 Order Status After Payment。默认：Pending。

On Hold (Review) Status：Wompi 批准的金额或币种与订单总额不符，或者在订单已取消后才批准付款。备注会说明原因；订单不会被标记为已付款。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Payment Status：最近一次付款尝试中的待处理交易被拒绝或以错误结束。默认：Failed。

Cancelled Order Status：最近一次付款尝试中的待处理交易已在 Wompi 中作废。对处于此状态的订单批准的付款会将其置于保留状态，而不是标记为已付款。默认：Canceled。

高级

Debug log：将付款和 webhook 活动写入 OpenCart 日志文件夹（storage/logs，在 OpenCart 4 中为 system/storage/logs）中的 wompi_p_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会记录。密钥、机密值和顾客数据绝不会写入日志。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展时会删除扩展设置和日志。订单和 Wompi 付款尝试始终保留。默认：关闭。

Import / Export

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

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Wompi）。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会创建一次带有自身参考号（OC-、订单号和时间戳）的付款尝试，使用完整性密钥对其签名，并将顾客带到 Wompi Web Checkout，以 COP 显示订单总额。顾客的电子邮件和付款地址的名称会传递给 Wompi。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并在结账页面底部点击 Confirm Order。如果没有付款地址，则名称取自订单或配送地址。

在 Wompi 页面，顾客可使用您 Wompi 账户中启用的任何付款方式付款。随后，Wompi 会将顾客带回您的商店。只有当 Wompi 确认后，订单才会被标记为已付款：通过经签名的事件，或在顾客返回时由服务器向 Wompi API 发起的请求。返回地址中的交易号本身不被信任，只接受在该尝试所在环境中为该订单创建的交易。页面刷新时，交易最多每 20 秒重新检查一次。

交易获得批准后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。对于待处理的付款（例如 PSE、Nequi 或现金付款），页面会显示 Your Wompi payment is pending confirmation (for example PSE, Nequi or a cash payment). We will process the order as soon as Wompi confirms the payment. 对于处于保留状态的订单，页面会显示 We have received your Wompi payment and are reviewing it. We will contact you if anything is needed. 如果待处理的付款之后被拒绝，页面会显示 Your Wompi payment was not approved. Please contact us. 如果付款被作废，页面会显示 Your Wompi payment was voided and this order was cancelled. Please contact us.

如果顾客返回时 Wompi 尚未确认交易，页面会显示 We are waiting for Wompi to confirm your payment. You will receive an e-mail as soon as it is confirmed.，并带有 Check again 和 Back to checkout 按钮。Wompi 事件一到达，就会设置订单状态。

如果付款被拒绝，订单将保持无状态，购物车会被保留。顾客会回到结账页面，并看到 Your Wompi payment was not approved (...). You can try again or choose another payment method. 以及 Wompi 给出的原因。付款被作废时显示 Your Wompi payment was voided. You can try again or choose another payment method. 如果顾客未付款就离开了 Web Checkout，消息为 Your Wompi payment was not completed. You can try again or choose another payment method. 每次新的尝试都会获得新的参考号。每次显示 Confirm Order 步骤时，OpenCart 都会创建一个新订单，但一个购物车只会付款一次：购物车中的某个订单一旦已付款、正在等待付款或处于保留状态，顾客就会被带到成功页面，而不是再次付款。

在 OpenCart 4 中，这些消息会显示在结账页面上方。OpenCart 4 会为结账保留一个订单，并在每次显示 Confirm Order 步骤时更新它：付款被拒绝或未完成后，顾客会用新的尝试支付同一订单。如果该订单在此期间未付款即已关闭（例如其待处理的 PSE 或 Nequi 付款之后被拒绝或作废，或者您已取消该订单），或者付款开始后购物车又有变化，订单会离开结账流程，顾客会看到 Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. 下一次 Confirm Order 会以新订单支付购物车。

只有在许可证有效、当前模式的四个密钥均已设置、顾客以 COP 结账且总额至少为 COP 1,500 时，才会显示该付款方式。如果无法开始付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短消息：

即使商店处于维护模式，Events URL 也可以正常工作，因为 OpenCart 允许付款扩展的请求通过。在 OpenCart 4 中，扩展的启动动作会放行 Events URL 和顾客的返回。

该扩展不能通过 OpenCart 退款。您的网站上没有已保存的银行卡、订阅或银行卡输入字段：所有付款数据都在 Wompi 页面输入。

订单

订单状态

无状态（缺失订单）：顾客已被带到 Wompi 但未付款、付款被拒绝，或 Wompi 尚未报告该交易。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。

Awaiting Payment Status（默认 Pending）：Wompi 将交易报告为待处理，例如等待确认的 PSE、Nequi 或现金付款。订单会一直等待，直到 Wompi 批准或拒绝。批准后，订单会转为 Order Status After Payment。

Order Status After Payment（默认 Processing）：交易已按订单金额（COP）获得批准。备注会显示交易、付款方式类型（例如 CARD、PSE 或 NEQUI）、参考号、金额和环境。

On Hold (Review) Status（默认 Pending）：Wompi 批准的金额或币种与订单总额不符（例如付款开始后购物车被修改），或者付款是在订单取消后才获得批准的。订单不会被标记为已付款。备注会说明情况。请在 Wompi 后台检查该付款，然后完成订单或退款。

Failed Payment Status（默认 Failed）：最近一次付款尝试中的待处理交易被拒绝或以错误结束。Wompi 的消息会被添加到备注中。较早尝试的结果不会更改订单。

Cancelled Order Status（默认 Canceled）：最近一次付款尝试中的待处理交易已在 Wompi 中作废。

当已有状态的订单发生变化（例如由等待转为已付款或失败）时，OpenCart 会通知顾客。如果同一订单已付款，或同一购物车中已付款的另一笔订单又收到了第二笔已批准的付款，则订单不会改变。备注会要求您在 Wompi 后台退还重复的付款。如果付款交易在 Wompi 中被作废，备注会要求您检查该订单。重复的事件和返回操作绝不会产生重复的备注或付款。

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

VibeFox Wompi Payment 选项卡

在 Sales > Orders 中打开一个通过 Wompi 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Wompi Payment 选项卡会显示 Reference、Transaction ID、Status（包括 Wompi 状态）、Requested 金额、Transaction amount、Payment method、Wompi message、沙盒付款的 SANDBOX 标签、购物车的 Payment attempts（如果有多次尝试）以及订单的 Wompi notes。该选项卡会显示给有权访问该扩展的用户。

退款

退款不会从 OpenCart 发出。请在 Wompi 商户后台退款或作废付款，然后手动在 OpenCart 中记录退款。在 Wompi 中对付款交易进行的作废操作会以备注的形式添加到订单中。Sales > Returns 中的商品退货不会通过 Wompi 退还款项。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。位于 Extensions > Extensions > Payments > VibeFox Wompi Payment > Edit 页面顶部、设置上方的第一个区块是许可证区块 License — VibeFox Wompi Payment。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方是 Product: opencart-payment-wompi 一行和 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Wompi。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户，仍会在商店中看到该付款方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可关闭，并在 7 天内隐藏。现有订单不受影响：已经开始的付款仍会通过 Wompi 事件和顾客返回而得到确认。

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

故障排除

结账时不显示 Wompi：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的四个密钥是否均已设置（设置页面上的状态框会列出缺少的密钥）。另请检查顾客是否以 COP 结账，以及总额是否至少为 COP 1,500。还要检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Events URL 未正常工作。在 Wompi 后台检查您所使用环境（沙盒或生产）的 Events URL 是否已设置，并且与设置中显示的完全一致。检查该环境的事件密钥是否位于对应的部分。顾客付款后返回商店时，订单也会获得状态。

Events URL answers Not configured：事件所属环境的事件密钥为空。请将其粘贴到设置中。

Events URL answers Invalid signature：事件密钥属于其他环境或其他账户。请从 Wompi 后台重新复制。

Events URL answers Transaction lookup failed：Wompi API 没有返回该交易，例如因为私钥错误或网络问题。Wompi 之后会重新发送该事件。

Events URL answers Retry：订单在同一时刻正被另一个请求确认，或者无法设置订单状态。Wompi 之后会重新发送该事件。请查看 Log 字段了解原因。

Events URL answers Environment mismatch：沙盒交易对应了生产付款尝试，或者反过来。沙盒付款绝不会确认生产订单。

Events URL answers Unknown reference：交易参考号看起来像本商店的参考号，但从未在此发出，例如来自同一 Wompi 账户上的另一个 OpenCart 商店。其他系统的参考号会收到 Ignored: not an OpenCart reference 的回复。

The Events URL shows Method not allowed in the browser：这是正常现象。该 URL 只接受来自 Wompi 的请求。

The key does not start with ... warning on save：某个密钥被粘贴到了错误的部分。沙盒密钥以 pub_test_、prv_test_、test_events_ 和 test_integrity_ 开头，生产密钥以 pub_prod_、prv_prod_、prod_events_ 和 prod_integrity_ 开头。

Order is in the review status：请阅读 VibeFox Wompi Payment 选项卡中的备注（参见订单状态），然后在 Wompi 后台完成订单或退款。

Other errors：请查看扩展页面上的 Log 字段以及订单中的 Wompi notes。错误始终会被记录。如需更多详情，请开启 Debug log。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Wompi Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及在维护模式下放行 Events URL 的启动动作）。如果 Delete data on uninstall 已开启，其他设置（标题、描述、沙盒模式、密钥、日志记录）和日志都会被删除。如果已关闭，它们会被保留，以便日后重新安装时使用。Wompi 付款尝试始终会被保留，因此即使在重新安装之后，旧付款的延迟事件仍会被识别。现有订单会保留其付款备注。

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

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