VibeFox Wompi for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
店铺货币：哥伦比亚比索（COP）。Wompi Colombia 仅以 COP 收款，对于其他货币的订单，付款方式会被隐藏。
Wompi 账户：一个 Wompi Colombia 商户账户。每个环境（沙盒和生产）各有四个密钥：公钥、私钥、事件密钥（events secret）和完整性密钥（integrity secret）。您可以在 Wompi 商户后台（comercios.wompi.co）的开发者部分找到它们。Wompi El Salvador 和 Panama 使用不同的 API，不受支持。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_wompi_payment 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 在 WooCommerce > Settings > General 中，将店铺货币设置为哥伦比亚比索（COP）。
4. 打开设置：WooCommerce > Settings > Payments > Wompi，或在插件页面点击插件名称下的 Settings。
5. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
6. 从 Wompi 商户后台粘贴沙盒和生产环境的密钥，并在 Wompi 中设置 Events URL（参见配置）。
7. 开启 Enable/Disable。在沙盒模式下测试一笔付款，然后取消勾选 Sandbox mode，即可接受真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > Wompi。字段上方的状态框会显示当前模式，即 SANDBOX 或 PRODUCTION。如果缺少此模式下的某个密钥，状态框会列出该密钥，并说明在结账时隐藏该付款方式，直到此环境的所有密钥都已设置。所有密钥设置完成后，状态框会说明是否会收取真实付款。保存时，如果某个密钥的开头与其所在部分的前缀不符，或者 Wompi 已启用但因缺少密钥而在结账时隐藏，插件都会发出警告。在付款方式列表中，在当前模式的四个密钥全部设置完成之前，Wompi 会被标记为需要设置。1.0 版本的密钥会在更新时自动移到对应的 Sandbox 或 Production 部分。
常规
Enable/Disable：Enable Wompi 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Wompi。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.
Wompi 账户
从 Wompi 商户后台（comercios.wompi.co）的开发者部分复制密钥。每个环境都有各自的公钥、私钥、事件密钥和完整性密钥。
Sandbox mode：Use the Wompi sandbox (sandbox keys, no real money)。此选项会同时切换密钥和 Wompi API（sandbox.wompi.co 或 production.wompi.co）。订单会保留其付款时所在的环境。默认：开启。取消勾选即可接受真实付款。
沙盒密钥
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_...）。
Events URL（webhook）
Wompi 事件会通知您的店铺某笔交易已发生变化。在 Wompi 商户后台的开发者部分，为沙盒和生产环境分别设置此设置部分中显示的 Events URL。其格式类似 https://your-site/wc-api/wompi_p/。请完全按照设置中显示的样子复制该 URL。
插件使用以下事件：
其他事件会返回 Ignored。每个事件都会使用其所在环境（沙盒或生产）的事件密钥进行验证。签名无效的事件会被拒绝。验证通过后，系统会从 Wompi API 读取交易，并且只使用这些数据。如果没有设置 Events URL，则只有在顾客付款后返回店铺时，订单才会被确认。
高级
Debug log：Log payment and webhook activity 会将付款和事件活动写入 WooCommerce > Status > Logs，来源为 wcp_wompi_payment。即使此选项关闭，错误也始终会被记录。密钥、私密信息和顾客数据绝不会被记录。默认：关闭。
Delete data on uninstall：Remove the plugin settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单数据始终保留。默认：关闭。
结账
顾客选择付款方式（默认为 Wompi）并提交订单。在沙盒模式下，结账页面会在描述下方显示 Sandbox mode: no real payment is made. 插件会使用自己的参考编号（WC-、订单号和时间戳）创建一次付款尝试，用完整性密钥对其签名，并以 COP 计价的订单总额将顾客引导至 Wompi Web Checkout。顾客的账单电子邮件和姓名会传递给 Wompi。订单备注会记录环境、参考编号和金额。
在 Wompi 页面上，顾客可以使用您 Wompi 账户中启用的任意付款方式付款。之后，Wompi 会将顾客带回您店铺的订单确认页面。只有在 Wompi 确认后，订单才会标记为已付款：通过已签名的事件确认，或在顾客到达该页面时由服务器向 Wompi API 发出请求确认。返回地址中的交易编号本身不被信任。页面刷新时，交易最多每 20 秒重新检查一次。
只有为该订单创建的交易才能支付该订单，并且仅限于该次尝试所在的环境。顾客可以重新支付未付款的订单，例如通过 Pay for order 页面。每次尝试都会获得新的参考编号。
只有在许可证有效、当前模式的四个密钥全部设置、订单货币为 COP 且总额至少为 COP 1,500 时，才会显示该付款方式。如果无法开始付款，顾客会看到一条简短的消息，并可以选择其他付款方式：
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。已包含哥伦比亚和西班牙的西班牙语翻译。
插件不通过 WooCommerce 退款。您的网站上没有保存的银行卡、订阅或银行卡输入字段：所有付款信息都在 Wompi 中输入。
订单
订单状态
Pending payment：顾客已被引导至 Wompi 但尚未付款，或 Wompi 尚未确认该交易。
On hold (pending payment)：Wompi 将交易报告为待处理，例如等待确认的 PSE、Nequi 或现金付款。订单会保持在保留状态，直到 Wompi 批准或拒绝该交易。
Processing or Completed：交易已获批准。适用 WooCommerce 标准：处理中；若订单仅包含虚拟可下载商品，则为已完成。订单备注会显示 Wompi 交易、付款方式类型（例如银行卡、PSE 或 Nequi）和参考编号。订单的交易 ID 即为 Wompi 交易 ID。
On hold after payment：Wompi 批准的金额或币种与订单总额不符（例如，付款开始后订单被修改），或者付款是在订单被取消之后才获得批准的。订单不会被标记为已付款。订单备注会对此加以说明。请在 Wompi 后台核查该付款，然后处理订单或退款。
Failed：最近一次付款尝试的交易被拒绝或以错误结束。Wompi 的消息会添加到备注中。较早尝试的结果不会改变订单。
Cancelled：最近一次付款尝试的交易在订单付款之前已在 Wompi 中被撤销。
如果已付款的订单又收到第二笔已批准的付款，订单不会改变。备注会提示您在 Wompi 后台退还重复付款。如果付款交易在 Wompi 中被撤销，备注会提示您检查该订单。对已退款订单的迟到付款只会添加备注。重复的事件和顾客的返回操作绝不会产生重复的备注、电子邮件或库存变动。
退款
退款不会从 WooCommerce 发起。请在 Wompi 商户后台退款或撤销该付款，然后在 WooCommerce 中记录一笔手动退款。在 Wompi 中进行的撤销会作为备注添加到订单中。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Wompi 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，Wompi 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会通过 Wompi 事件和顾客返回操作得到确认。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Wompi 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的四个密钥是否全部设置（设置页面上的状态框会列出缺少的密钥）。另外，请检查订单货币是否为 COP，以及订单总额是否至少为 COP 1,500。
付款已完成，但订单仍停留在 Pending payment：Events URL 无法正常工作。在 Wompi 后台，请检查您所用环境（沙盒或生产）的 Events URL 是否已设置，并且与设置中显示的完全一致。同时检查该环境的事件密钥是否位于对应的部分中。顾客付款后返回店铺时，订单也会被确认。
Events URL 返回 Not configured：事件所属环境的事件密钥为空。请将其粘贴到设置中。
Events URL 返回 Invalid signature：事件密钥属于其他环境或其他账户。请从 Wompi 后台重新复制。
Events URL 返回 Transaction lookup failed：Wompi API 未返回该交易，例如私钥错误或网络问题。Wompi 稍后会重新发送该事件。
Events URL 返回 Busy, retry：订单在同一时刻正被另一个请求更新。Wompi 稍后会重新发送该事件。
Events URL 返回 Environment mismatch：沙盒交易被用于生产付款尝试，或反之。沙盒付款绝不会确认生产订单。
保存时出现 "The key does not start with ..." 警告：密钥被粘贴到了错误的部分。沙盒密钥以 pub_test_、prv_test_、test_events_ 和 test_integrity_ 开头，生产密钥以 pub_prod_、prv_prod_、prod_events_ 和 prod_integrity_ 开头。
订单处于 On hold，并附有金额相关的备注：已批准的金额或币种与订单总额不同。请在 Wompi 后台核查该付款，并手动完成或退款该订单。
其他错误：请打开订单备注或 WooCommerce > Status > Logs，来源为 wcp_wompi_payment。错误始终会被记录。如需更多细节，请开启 Debug log。如果开发者的 Wompi 账户接受其他货币，可通过 wompi_p_supported_currencies 过滤器允许使用该货币。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额并点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件会继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有在 Delete data on uninstall 已开启的情况下，网关设置和插件日志才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注、Wompi 数据和交易 ID。
Wompi 是其各自所有者的商标。本插件与 Wompi 没有关联，也未获得 Wompi 的认可。