VibeFox Ozow for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。

PHP：8.0 或更高版本。

货币：南非兰特（ZAR）。其他货币下将隐藏此付款方式。Ozow 以整分收款，因此 WooCommerce 应使用 2 位小数。

Ozow 账户：Ozow 商户账户，以及您的 Ozow 站点的 Site Code 和 Private Key，可在 Ozow 商户后台获取。API Key 为可选项，但建议使用。Ozow 对测试和正式付款使用相同的 Site Code 和密钥。

可访问的站点：您的站点必须可以从互联网访问，不能处于维护模式，不能启用密码保护，也不能有防火墙阻止 Ozow，以便 Ozow 的通知能够送达。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_ozow_pay 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Ozow > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 从 Ozow 商户后台输入 Site Code 和 Private Key，最好也输入 API Key。

6. 开启 Enable/Disable。在开启 Test mode 的情况下进行一笔测试付款，然后关闭测试模式以接受真实付款。

配置

所有设置都在一个页面中：WooCommerce > Settings > Payments > Ozow。在字段上方，当缺少 Site Code 或 Private Key 时（此时 Ozow 在结账页面中隐藏）、店铺货币不是 ZAR 时，以及 WooCommerce 使用超过 2 位小数时，页面都会发出警告；测试模式开启时，页面还会显示 Test mode is on: no real payments are accepted. Do not ship orders paid in test mode.。在付款方式列表中，在填写 Site Code 和 Private Key 之前，Ozow 会被标记为需要设置。

常规

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

Title：顾客在结账时看到的付款方式名称。默认：Instant EFT (Ozow)。

Description：结账时显示在付款方式下方的文字。默认：Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment。测试模式下，其下方会添加一行 TEST MODE: no money will be charged.。

Ozow 凭据

从 Ozow 商户后台（Merchant details / Sites）复制 Site Code、Private Key 和 API Key。该部分会链接到 hub.ozow.com 上的 Ozow 集成文档。

Site Code：接收付款的 Ozow 站点的 Site Code。针对其他 Site Code 的响应会被拒绝。

Private Key：为每个付款请求签名，并验证每个 Ozow 响应。请妥善保密。没有它，此付款方式会被隐藏，且不会接受任何 Ozow 响应。

API Key (recommended)：可选。使用 API Key 时，每笔成功的付款在订单标记为已付款之前，还会通过 Ozow GetTransaction API 进行确认。API 必须报告该订单的付款已完成，且金额、货币和 Site Code 一致。

Test mode：Enable Ozow test mode。Ozow 测试使用相同的 Site Code 和密钥：付款以 IsTest=true 创建，不会产生实际资金流动。在测试模式下付款的订单会添加订单备注；请勿发货。关闭测试模式即可接受真实付款。测试付款在正式模式下绝不会使订单变为已付款。默认：开启。

付款通知

每次付款时，通知、成功、取消和错误的 URL 都会发送给 Ozow，因此无需在 Ozow 后台进行任何配置，除非您的 Ozow 站点设置了固定 URL。本部分会显示通知 URL，其格式类似 https://your-site/wc-api/ozow_pay/?ozow_notify=1。如果您的 Ozow 站点使用固定 URL，请完全按照设置中显示的内容复制。

高级

Debug log：Log payment requests and Ozow responses 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_ozow_pay。错误和警告始终会被记录。密钥、哈希和顾客数据绝不会被记录。默认：关闭。

Delete data on uninstall：Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept)。默认：关闭。

结账

顾客选择付款方式（默认为 Instant EFT (Ozow)）并下单。插件会将顾客带到 Ozow 托管的付款页面，其中包含一个以 ZAR 计算的订单总额的签名请求。银行对账单上的参考信息为 Order 加订单号（最多 20 个拉丁字母、数字、空格和连字符）。顾客的姓名会传递给 Ozow。在 Ozow 页面上，顾客选择南非银行，并在网上银行应用中确认付款。

随后，Ozow 会通知店铺并将顾客送回。两者都包含相同的签名响应，并以相同方式处理，因此即使其中一个丢失，订单也会更新。只有在 Ozow 确认付款后，订单才会标记为已付款：哈希必须能用您的 Private Key 校验，Site Code 必须是您的，响应必须包含该订单的密钥，且金额和货币必须与订单一致。使用 API Key 时，还会通过 GetTransaction API 核对付款。

付款成功后，顾客会进入订单已接收页面。如果 Ozow 尚未确认付款，页面会显示 We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again.。如果订单处于保留状态，则显示 Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed.

如果顾客在 Ozow 页面取消，或付款失败，订单会变为 Failed，顾客返回 Pay for order 页面，并显示 The Ozow payment was cancelled. You can try again or choose another payment method. 或 The Ozow payment was not completed. You can try again or choose another payment method. 顾客可以再次支付同一订单。

该付款方式适用于经典结账、Checkout 区块以及 Pay for order 页面（仅限 ZAR 订单）。它兼容 WooCommerce 高性能订单存储（HPOS）。

插件仅接受以 ZAR 进行的一次性付款。不支持通过 WooCommerce 退款、订阅、保存银行账户或令牌化，也不支持从后台发送付款链接。

订单

订单状态

Pending payment：顾客已被转到 Ozow，但尚未付款，或 Ozow 尚未确认付款。

Processing：付款已确认。这是付款后 WooCommerce 的标准状态；仅包含虚拟可下载商品的订单会变为已完成（Completed）。订单备注会显示金额和 Ozow 交易 ID，以及付款是否已由 GetTransaction API 确认。订单的交易 ID 即为 Ozow TransactionId。测试付款会获得备注 TEST MODE — no money was received, do not ship this order.

On hold：订单备注会说明原因。Ozow 或银行正在核查该付款（Ozow 发送最终状态后，订单会更新）；已付金额或货币与订单不一致；订单已被取消后又收到付款；或者在使用 API Key 时，GetTransaction API 尚未能确认付款，或与付款情况相矛盾。请在 Ozow 后台核对付款并更改订单状态。如果 API 无法响应，下一次 Ozow 通知会完成该订单。

Failed：顾客取消了付款、付款被中止，或 Ozow 报告了错误。顾客可以从该订单重新付款。

已付款的订单绝不会被改回，已取消或已退款的订单也绝不会重新打开。如果同一已付款订单又收到第二笔付款，备注会提示您在 Ozow 后台退还重复付款。如果订单因其他原因（例如由您设置）而处于保留状态，之后的付款只会添加备注，您需要自行将订单设为 Processing。

退款

不支持通过 WooCommerce 退款。请在 Ozow 商户后台退还付款，并手动在 WooCommerce 中记录退款。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Ozow 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Ozow。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账页面中没有 Ozow：请检查许可证是否有效、Enable/Disable 是否开启、Site Code 和 Private Key 是否已填写，以及店铺或订单货币是否为 ZAR。缺少任何项目时，设置页面都会显示警告。

付款已完成，但订单仍为 Pending payment：Ozow 通知未能到达店铺，顾客也未返回。请检查您的站点能否从互联网访问（没有维护模式、密码保护或阻止 Ozow 的防火墙）。如果您的 Ozow 站点设置了固定 URL，请检查通知 URL 是否与设置中显示的完全一致。开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_ozow_pay。

通知返回 Invalid hash：设置中的 Private Key 不属于发送该响应的 Ozow 站点。请从 Ozow 商户后台重新复制。

通知返回 Unknown site：该响应来自另一个 Ozow 站点。请检查 Site Code。

通知返回 Order mismatch 或 Order not found：该响应不属于本店铺的订单。不会做任何更改。

通知返回 Gateway not configured：缺少 Site Code 或 Private Key。请填写后，Ozow 可能会重试。

通知返回 Order busy：同一订单的另一个 Ozow 响应正在同时处理。该响应不会被应用；下一次通知或顾客返回时会应用它。

通知返回 Payment not confirmed yet：使用 API Key 时，GetTransaction API 无法确认付款。订单处于保留状态，下一次通知会将其完成。如果仍处于保留状态，请检查 API Key 以及 Ozow 后台中的付款情况。

顾客看到 Ozow accepts payments in South African rand (ZAR) only：订单使用的是其他货币。该订单无法使用 Ozow。

测试付款没有使订单付款：网关处于正式模式。测试付款在正式模式下绝不会使订单变为已付款；订单上的备注会说明此情况。

付款后订单处于 On hold：请阅读订单备注，并在 Ozow 后台核对付款，然后将订单设为 Processing，或在 Ozow 中退款。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最近一次已知的状态继续工作。

卸载

停用插件会保留所有数据。要移除插件，请在 Plugins 页面中停用并删除。此插件的许可证密钥和许可证状态始终会被删除。网关设置、插件的其他选项以及日志只有在 Delete data on uninstall 开启时才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注和交易 ID。

Ozow 是其各自所有者的商标。本插件与 Ozow 无关联，也未获得 Ozow 的认可。