VibeFox Ozow for OpenCart — 帮助

系统要求

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

PHP: 8.0 或更高版本。

货币：南非兰特（ZAR）。商店必须设有 ZAR 货币（System > Localisation > Currencies），并且只有当顾客使用 ZAR 结账时才会显示该付款方式。Ozow 按整分收费，因此该货币应使用 2 位小数。

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

可访问的站点：您的商店必须可以从互联网访问，不能有密码保护或防火墙阻止 Ozow，这样 Ozow 通知才能送达。即使商店处于维护模式，通知也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动操作，放行来自 Ozow 的通知和客户的返回。

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

安装

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

OpenCart 3

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

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

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

4. 从 Ozow 商户后台输入 Site Code 和 Private Key，最好也填写 API Key。通知和返回 URL 会在每次付款时发送给 Ozow，因此无需在 Ozow 后台进行任何设置。

5. 开启 Enable/Disable 并点击 Save。在开启 Test mode 的情况下进行一次测试付款，然后关闭测试模式，即可接受真实付款。

OpenCart 4

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

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

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

4. 输入许可证密钥和 Ozow 密钥，并按照 OpenCart 3 步骤 3 至 5 的方式进行测试付款。两个版本的设置页面及其字段相同。只有通知和返回 URL 不同（参见付款通知）；它们同样会在每笔付款时发送给 Ozow。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Ozow Pay > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在以下情况提示您：缺少 Site Code 或 Private Key（此时 Ozow 在结账时会被隐藏）；商店的默认货币不是 ZAR；货币的小数位超过 2 位（请在 System > Localisation > Currencies 中将其设为 2）；测试模式开启时，显示 Test mode is on: no real payments are accepted. Do not ship orders paid in test mode.。若您没有修改扩展的权限，页面可以显示设置，但无法保存。

除了 Title 超过 128 个字符（The title must be no longer than 128 characters.）之外，Ozow 的字段从不阻止保存。OpenCart 的字段会进行检查：Sort Order 必须是整数（允许负数），Total 必须是大于或等于 0 的数字，地理区域和订单状态必须存在。如果其中任何一项有误，错误信息会指明该字段，且不会保存任何内容。

Ozow

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

Title: 顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。最多 128 个字符；如果留空，则显示 Instant EFT (Ozow)。默认值：Instant EFT (Ozow)。

Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认值：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.（仅当描述不为空时）。

Sort Order: Ozow 在结账时付款方式中的排列位置。可留空或输入一个整数。

Geo Zone: 仅对所选地理区域内的付款地址提供 Ozow。默认值：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，如果商店不要求付款地址，则使用配送地址。

Total: 订单金额必须达到的门槛（以商店默认货币计）才会提供 Ozow。留空则对任何金额都提供 Ozow。

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 一致。

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

Test mode: Ozow 在测试中使用相同的 Site Code 和密钥：付款会以 IsTest=true 创建，且不会有资金流动。在测试模式下付款的订单会添加备注；请勿发货。关闭测试模式即可接受真实付款。在正式模式下，测试付款永远不会支付订单。默认值：开启。

付款通知

本节显示扩展在每笔付款时发送给 Ozow 的四个 URL：Notification URL（Ozow 将付款通知发送到此处）、Success URL、Cancel URL 和 Error URL（Ozow 将顾客返回到此处）。它们的样子类似 https://your-store/index.php?route=extension/payment/wcp_ozow_pay/notify 和 https://your-store/index.php?route=extension/payment/wcp_ozow_pay/back&ozow_return=success；在 OpenCart 4 中则分别为 https://your-store/index.php?route=extension/wcp_ozow_pay/payment/wcp_ozow_pay.notify 和 https://your-store/index.php?route=extension/wcp_ozow_pay/payment/wcp_ozow_pay.back&ozow_return=success，由您 OpenCart 安装的前台地址生成。无需在 Ozow 后台进行任何设置。如果您的 Ozow 站点设置了固定 URL，请完全按照设置页面所示进行复制。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（即缺失订单）。只有在 Ozow 发送了签名正确的响应之后，订单才会获得状态。取消或失败的付款会使订单保持无状态，顾客会带着保留的购物车返回结账页面。下面的每个字段都列出了您 OpenCart 的订单状态。

Order Status After Payment: Ozow 报告付款为 Complete，且金额和货币与预期一致（若设置了 API Key，则由 GetTransaction 确认）。默认值：处理中。

Awaiting Ozow Payment Status: Ozow 或银行正在调查该付款（Ozow 状态 PendingInvestigation）。当 Ozow 报告 Complete 时，订单会获得付款后的状态。默认值：待处理。

On Hold (Review) Status: 该付款需要您审核（参见订单状态）。订单不会被标记为已付款。默认值：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Failed Payment Status: 调查中的付款，其后被 Ozow 报告为 Cancelled、Error 或 Abandoned。默认值：失败。

Cancelled Order Status: 您的商店用于已取消订单的状态。为此类订单收到的付款会将其置于审核状态，而不是标记为已付款。扩展从不设置此状态。默认值：已取消。

Refunded Order Status: 您的商店用于已退款订单的状态。为此类订单收到的付款只会添加一条备注。扩展从不设置此状态。默认值：已退款。

高级

Debug log: 将付款请求和 Ozow 响应写入 OpenCart 日志文件夹（storage/logs）中的 ozow_p_debug.log.php。该文件无法通过网页打开，当其达到 5 MB 时会被移动到 ozow_p_debug.old.log.php。错误和警告始终会被记录。密钥、哈希值、令牌和顾客数据从不记录。默认值：关闭。

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

Delete data on uninstall: 开启时，卸载扩展会删除网关设置和日志。订单的 Ozow 数据始终保留。默认值：关闭。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。Private Key 和 API Key 不会被导出。

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Instant EFT (Ozow)）。在 Confirm Order 步骤，顾客会看到您的描述以及提示 You will be redirected to Ozow to choose your bank and approve the payment. OpenCart 在此步骤创建订单，此时仍无状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会将顾客带到 Ozow 托管的付款页面，并附带以 ZAR 计的订单总额的签名请求。银行对账单上的参考信息为 Order 加订单号（最多 20 个拉丁字母、数字、空格和连字符）。顾客的姓名会传递给 Ozow。在 Ozow 页面，顾客选择一家南非银行，并在银行应用中批准付款。

随后，Ozow 会通知商店并将顾客送回。两者都携带相同的签名响应，并以相同方式处理，因此即使其中一个丢失，订单也能获得状态。只有在 Ozow 确认后，订单才会被标记为已付款：哈希必须能用您的 Private Key 验证，Site Code 必须是您的，响应必须属于该订单的这次付款尝试，且金额和货币必须与订单一致。若设置了 API Key，还会通过 GetTransaction API 检查付款。然后，订单会以标准的 OpenCart 方式获得状态，并发送常规订单电子邮件、更新库存。

付款成功后，顾客会看到 OpenCart 的订单成功页面。如果 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. 如果被调查的付款后来失败，或未付款的订单已被取消，则显示 Your Ozow payment was not completed. Please contact us about this order.（在 OpenCart 4 中，顾客会改为被送回结账页面，见下文）。如果顾客返回时 Ozow 仍未确认付款，将显示 Payment confirmation 页面，其中包含等待文字以及 Check again 和 Back to checkout 按钮。

如果顾客在 Ozow 页面取消，或付款失败，订单会保持无状态。顾客会带着相同的购物车返回结账页面，并看到 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. 在 OpenCart 4 中，这些消息显示在结账页面上方。

OpenCart 3 会在每次显示 Confirm Order 步骤时创建一个新订单。OpenCart 4 为结账保留一个订单并对其进行更新，因此在付款被取消或失败后，顾客会以新的尝试支付同一个订单。如果同一购物车的另一个订单已付款或正在等待 Ozow，顾客会直接进入成功页面，且第二个订单的迟到付款不会被应用：已付款订单上的备注会提醒您在 Ozow 后台退还重复付款。

如果购物车对应的某个订单已付款，之后被您取消或退款，顾客会被送回结账页面，并用新订单支付购物车。在 OpenCart 3 中，提示信息为 This order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

OpenCart 4 会一直将订单保留在结账流程中，直到显示成功页面为止。当顾客再次点击 Confirm Order 或从 Ozow 返回，而该订单已关闭时，顾客会被带回结账页面并看到提示，下一次 Confirm Order 会支付一个新订单：Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.（例如调查中的付款失败，或您取消了未付款的订单）或 Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.（订单已付款，之后被取消或退款）。如果该订单已付款，且购物车现在包含其他商品或数量，Confirm Order 会显示 Your previous order has already been paid. Your cart has changed since — please confirm the order again to pay for the current cart.

如果结账不是以 ZAR 进行，顾客会看到 Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

该扩展仅接受 ZAR 的一次性付款。它不支持从 OpenCart 退款、订阅、保存银行账户或令牌化，也不支持从后台发送付款链接。

订单与退款

订单状态

无状态（缺失订单）：顾客已被发送到 Ozow，但尚未付款、已取消，或 Ozow 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

在 OpenCart 4 中，结账时未付款的订单可能会获得 Voided 状态，该状态会在顾客返回 Confirm Order 步骤时由 OpenCart 4 设置。扩展将此类订单视为无状态订单，之后的付款仍会确认该订单。

Order Status After Payment (default Processing): 付款已确认。备注会显示金额、Ozow 交易 ID，以及该付款是否已由 GetTransaction API 确认。测试付款会收到备注 TEST MODE — no money was received, do not ship this order.

Awaiting Ozow Payment Status (default Pending): Ozow 或银行正在调查该付款。当 Ozow 发送最终状态时，订单会被更新：成功时为 Order Status After Payment，失败时为 Failed Payment Status。

On Hold (Review) Status (default Pending): 备注会说明原因：已付金额或货币与订单不符；为已取消的订单收到了付款；或者在设置了 API Key 的情况下，GetTransaction API 暂时无法确认付款或与之矛盾。请在 Ozow 后台核实付款并更改订单状态。如果 API 无法响应，下一次 Ozow 通知会完成该订单。

Failed Payment Status (default Failed): 调查中的付款被取消、放弃或失败。之后针对该付款的成功 Ozow 响应仍会将订单标记为已付款。

已付款的订单永远不会被改回原状态，已取消或已退款的订单也永远不会被重新打开。如果已付款的订单又收到第二笔付款，备注会提醒您在 Ozow 后台退还重复付款。当扩展处于正式模式时，测试付款永远不会支付订单；备注会说明这一点。

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

VibeFox Ozow Pay 选项卡

在 Sales > Orders 中打开一个通过 Ozow 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Ozow Pay 选项卡会显示 Transaction reference（订单号）和尝试次数、Ozow transaction ID、Status、Requested 金额、Amount reported by Ozow、Ozow message、测试付款的 TEST MODE 标签，以及该订单的 Ozow notes。该选项卡对有权访问该扩展的用户显示。

退款

不支持从 OpenCart 退款。请在 Ozow 商户后台退还付款，然后在 OpenCart 中手动记录退款。Sales > Returns 中的商品退货不会通过 Ozow 退还资金。

许可证密钥

该扩展需要从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Ozow Pay 是 Extensions > Extensions > Payments > VibeFox Ozow Pay > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至的日期以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店移除该密钥）。其下方是 Product: opencart-payment-ozow 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言（包含英文和俄文）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。在商店地址更改之后，或在您的账户中释放了一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，扩展会继续以上次已知的状态运行。

一个密钥只适用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

Ozow 未出现在结账页面：检查许可证是否有效、Enable/Disable 是否开启、Site Code 和 Private Key 是否已填写，以及顾客是否以 ZAR 结账。还要检查付款地址是否位于所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。缺少任何内容时，设置页面都会显示警告。

付款已完成，但订单仍无状态：Ozow 通知未能到达商店，且顾客也没有返回。请检查您的商店是否可以从互联网访问（没有密码保护或阻止 Ozow 的防火墙）。如果您的 Ozow 站点设置了固定 URL，请检查这些 URL 是否与 Payment notifications 中显示的完全一致。开启 Debug log，并阅读扩展页面上的 Log 字段。

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

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

通知返回 Order mismatch 或 Order not found：该响应不属于在此商店发起的付款。不会更改任何内容。

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

通知返回 Payment not confirmed yet：该响应尚无法应用。若设置了 API Key，GetTransaction API 无法确认该付款（订单处于审核状态，下一次通知会完成它；如果它一直停留在该状态，请检查 API Key 以及 Ozow 后台中的付款）。如果同一购物车的顾客返回操作恰好在同一时刻正在处理，也会出现此响应；请查看日志。

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

测试付款未能支付订单：扩展处于正式模式。测试付款在正式模式下永远不会支付订单；订单备注或日志会说明这一点。

付款后订单处于审核状态：请阅读 VibeFox Ozow Pay 选项卡中的备注，并在 Ozow 后台核实付款，然后设置订单状态，或在 Ozow 中退款。

卸载

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

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

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