VibeFox Wompi for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在更低版本的 PHP 上。

币种：哥伦比亚比索（COP）。Wompi Colombia 以 COP 收款，购物车使用其他币种时将隐藏该付款方式。若店铺的默认币种不是 COP，配置页面会向您发出警告。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox Wompi Payment，然后点击 Configure。

3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块的 License key 中，然后点击 Activate（参见许可证密钥）。

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

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

安装时，模块会创建两个订单状态：Awaiting Wompi payment 和 Wompi payment on hold。PrestaShop 会为当时已存在的币种、国家和顾客群组提供一个新的付款模块。请在 Payment > Preferences 中确认已允许 COP。之后添加的国家必须在那里勾选，该国家的顾客才能看到 Wompi。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Wompi Payment > Configure。每个包含字段的部分都有自己的 Save 按钮，点击后会保存整个页面。字段上方的状态框显示当前模式，即 SANDBOX 或 PRODUCTION。如果缺少该模式的某个密钥，状态框会列出该密钥，并说明在该环境的所有密钥设置完成之前，结账时将隐藏此付款方式。所有密钥设置完成后，状态框会说明是否会收取真实付款。保存时，如果某个密钥不是以其所在部分的前缀开头，模块会发出警告；如果 Wompi 已启用，但因缺少密钥而在结账时被隐藏，模块也会发出警告。

Wompi

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

Title：顾客在结账时看到的付款方式名称。它也是保存在订单中的付款方式名称。默认值：Wompi。如果留空，则使用模块名称。

Description：结账时显示在付款方式下方的文字。默认值：Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Wompi 账户

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

Sandbox mode：使用 Wompi 沙盒（沙盒密钥，不产生真实资金）。它会同时切换密钥和 Wompi API（sandbox.wompi.co 或 production.wompi.co）。付款尝试会保留其所在的环境。默认值：on。关闭它即可接受真实付款。开启时，顾客会在付款方式下方看到 沙盒模式：不会产生真实付款。

沙盒密钥

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_...）。

公钥会显示在各自的字段中。已保存的私钥和密钥不会再次显示。字段保持为空，并显示 已保存：留空即可保留。 只有在需要更改时才输入新值。

Clear saved secrets：勾选任一环境的私钥或密钥，然后点击 Save 即可删除。留空的字段会保留已保存的值。

事件 URL（webhook）

Wompi 事件会通知您的店铺某笔交易已发生变化。请在 Wompi 商户后台的开发者部分，为沙盒和生产环境分别设置本部分显示的事件 URL。启用友好 URL 时，它的形式如 https://your-shop/module/wcp_wompi_payment/webhook，可能带有语言代码，例如 /es/。请完全按照设置中显示的内容复制该 URL。

模块使用此事件：

其他事件会以 Ignored 作为响应。每个事件都会使用其所在环境（沙盒或生产）的事件密钥进行验证。没有有效签名的 webhook 会被拒绝。验证后，模块会使用该环境的私钥从 Wompi API 读取交易，并且只使用这些数据。若没有事件 URL，只有在顾客付款后返回店铺时，才会创建订单。

高级

Debug log：将付款和 webhook 活动写入模块文件夹中的 logs/wompi_p_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。密钥、机密信息和顾客数据绝不会被记录。默认值：off。

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

Delete data on uninstall：开启时，卸载模块会删除模块设置和日志。Wompi 付款尝试记录和模块的订单状态始终保留，因此现有订单会保留其 Wompi 数据。默认值：off。

结账

在付款步骤中，顾客选择付款方式（默认为 Wompi）并确认。模块会以自己的参考号（PS-、购物车编号和时间戳）创建付款尝试，使用完整性密钥对其签名，并将顾客带到 Wompi Web Checkout，购物车总额以 COP 显示。顾客的电子邮件和账单地址的姓名会传递给 Wompi。此时尚未创建任何订单。

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

交易获得批准后，订单会被创建，顾客会看到标准的订单确认页面。对于待处理的付款（例如 PSE、Nequi 或现金付款），页面会显示 您的 Wompi 付款正在等待确认（例如 PSE、Nequi 或现金付款）。Wompi 确认付款后，我们将立即处理订单。 对于处于保留状态的订单，页面会显示 我们已收到您的 Wompi 付款，正在审核中。如需任何补充信息，我们会与您联系。 如果待处理的付款之后被拒绝，页面会显示 您的 Wompi 付款未获批准。请与我们联系。 如果付款被撤销，页面会显示 您的 Wompi 付款已被撤销，此订单已取消。请与我们联系。

如果顾客返回时 Wompi 尚未确认交易，页面会显示 我们正在等待 Wompi 确认您的付款。确认后，您将收到一封电子邮件。，并附带 Check again 按钮。Wompi 事件一到达就会创建订单。

如果付款被拒绝，则不会创建订单，购物车会被保留。顾客会返回结账页面，并显示 您的 Wompi 付款未获批准（...）。您可以重试或选择其他付款方式。，同时附上 Wompi 给出的原因。被撤销的付款会显示 您的 Wompi 付款已被撤销。您可以重试或选择其他付款方式。 如果顾客未付款就离开了 Web Checkout，消息为 您的 Wompi 付款未完成。您可以重试或选择其他付款方式。 每次新的尝试都会获得新的参考号。购物车一旦有了订单（已付款、待处理、付款错误或已取消），便无法再次付款：顾客会被引导至订单确认页面。

只有在许可证有效、当前模式的四个密钥均已设置、购物车币种为 COP 且已允许用于该模块，并且总额至少为 COP 1,500 时，才会显示该付款方式。如果无法开始付款，顾客会留在结账页面，并看到一条简短消息：

店铺处于维护模式时，事件 URL 仍然有效，并且不受店铺国家限制的影响。

模块不通过 PrestaShop 退款。您的网站上没有保存的银行卡、订阅或银行卡输入字段：所有付款数据都在 Wompi 上输入。

订单

订单状态

尚无订单：顾客已被引导至 Wompi 但未付款、付款被拒绝，或 Wompi 尚未确认交易。此时仅存在购物车。

Awaiting Wompi payment：Wompi 将交易报告为待处理，例如 PSE、Nequi 或现金付款正在等待确认。订单会一直等待，直到 Wompi 批准或拒绝为止。批准后，付款会被记录，订单转为 Payment accepted。

Payment accepted：交易已按 COP 购物车金额获得批准。付款会以 Wompi 交易 ID 记录，备注中会显示交易、付款方式类型（例如 CARD、PSE 或 NEQUI）、参考号、金额和环境。

Wompi payment on hold：Wompi 批准的金额或币种与订单总额不同（例如付款开始后购物车被修改），或者付款是在订单已被取消之后获得批准的。订单不会被标记为已付款。备注会对此作出说明。请在 Wompi 后台核实该付款，然后处理订单或退款。

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

Canceled：最近一次付款尝试中的待处理交易已在 Wompi 中被撤销。

如果同一笔已付款的订单又收到第二笔获批准的付款，订单不会发生变化。备注会提醒您在 Wompi 后台退还重复的款项。如果在 Wompi 中撤销了付款交易，备注会提醒您检查订单。对已退款订单的迟到付款只会添加一条备注。重复的事件和返回绝不会重复生成备注、电子邮件或付款记录。

Wompi 付款区块

订单页面会显示一个 Wompi payment 区块，其中包括参考号、交易 ID、状态（及 Wompi 状态）、请求金额、交易金额、付款方式、Wompi 消息；沙盒付款会显示 SANDBOX 标记；若购物车有多次付款尝试，则会显示 Payment attempts；此外还有订单的 Wompi notes。

退款

退款不会从 PrestaShop 发出。请在 Wompi 商户后台退款或撤销付款，然后在 PrestaShop 中手动记录退款。在 Wompi 中对付款交易进行的撤销会作为备注添加到订单中。

许可证密钥

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

没有有效许可证密钥时，Wompi 不会在结账时向顾客显示。若仍有付款被发起，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会通过 Wompi 事件以及顾客返回时得到确认。

许可证过期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

Wompi 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的四个密钥是否都已设置（设置页面的状态框会列出缺少的密钥）。另外请检查购物车币种是否为 COP，以及总额是否至少为 COP 1,500。在 Payment > Preferences 中，请检查模块是否允许用于 COP、顾客所在国家以及顾客所在群组。

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

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

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

事件 URL 返回 Transaction lookup failed：Wompi API 未返回该交易，例如私钥错误或网络问题。Wompi 之后会再次发送该事件。

事件 URL 返回 Retry：订单在同一时刻正被另一个请求确认，或者订单无法创建（例如模块已禁用）。Wompi 之后会再次发送该事件。请查看 Log 字段以了解原因。

事件 URL 返回 Environment mismatch：沙盒交易被用于生产环境的付款尝试，或反过来。沙盒付款绝不会确认生产订单。

事件 URL 返回 Unknown reference：交易参考号并非由本店铺签发，例如同一个 Wompi 账户被其他店铺使用。来自其他系统的参考号会以 Ignored 作为响应。

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

保存时出现密钥不以 ... 开头的警告：密钥被粘贴到了错误的部分。沙盒密钥以 pub_test_、prv_test_、test_events_ 和 test_integrity_ 开头，生产密钥以 pub_prod_、prv_prod_、prod_events_ 和 prod_integrity_ 开头。

订单处于 Wompi payment on hold 状态：请阅读 Wompi payment 区块中的备注（参见订单状态），然后在 Wompi 后台处理订单或退款。

其他错误：请查看模块页面上的 Log 字段以及订单的 Wompi notes。错误始终会被记录。如需更多详细信息，请开启 Debug log。

卸载

进入 Modules > Module Manager，打开 VibeFox Wompi Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Wompi 付款尝试记录以及 Awaiting Wompi payment 和 Wompi payment on hold 订单状态始终会保留，因此即使重新安装后，旧付款的迟到事件仍会被识别。现有订单会保留其付款备注和交易 ID。

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