VibeFox Ozow for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

货币：南非兰特（ZAR）。只有 ZAR 购物车才会显示该付款方式。Ozow 按整数分收费，因此货币应使用 2 位小数。

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

可访问的站点：您的店铺必须可以从互联网访问，且不能有密码保护或阻止 Ozow 的防火墙，以确保 Ozow 通知能够送达。即使店铺处于维护模式，通知仍会被接受。

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

安装

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

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

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

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

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

安装时，模块会创建两个订单状态：Awaiting Ozow payment 和 Ozow payment on hold。PrestaShop 会为所有货币、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中进行限制；在那里必须允许该模块使用 ZAR。之后启用的国家也必须在那里为该模块勾选。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Ozow Pay > Configure。每个带有 Save 按钮的部分都会保存整个页面。在字段上方，页面会在缺少 Site Code 或 Private Key 时发出警告（此时 Ozow 在结账时会被隐藏）、店铺默认货币不是 ZAR 时发出警告、货币小数位超过 2 位时发出警告（请在 International > Localization > Currencies 中将其设为 2），并且在测试模式开启期间显示 Test mode is on: no real payments are accepted. Do not ship orders paid in test mode.。

Ozow

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

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

已保存的密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it.。只有在需要更改时才输入新值。

Clear saved secrets：勾选 Private Key 或 API Key 并保存，即可删除已保存的密钥。空字段会保留已保存的值。

Test mode：Ozow 在测试中使用相同的 Site Code 和密钥：付款以 IsTest=true 创建，不会产生资金流动。在测试模式下付款的订单会收到一条订单消息；请勿发货。关闭测试模式即可接受真实付款。在正式模式下，测试付款绝不会使订单变为已付款。默认：on。

付款通知

通知、成功、取消和错误 URL 会随每笔付款发送给 Ozow，因此无需在 Ozow 后台进行任何配置，除非您的 Ozow 站点设置了固定 URL。本部分会显示全部四个 URL：Notification URL、Success URL、Cancel URL 和 Error URL。它们是您店铺的模块链接（控制器 notify 和 return）。如果您的 Ozow 站点使用固定 URL，请完全按照设置中显示的内容复制。

高级

Debug log：将付款请求和 Ozow 响应记录到模块文件夹中的 logs/ozow_p_debug.log.php（无法通过网页读取）。错误和警告始终会被记录。密钥、哈希、令牌和顾客数据从不记录。默认：off。

Log：显示日志的当前大小和末尾内容，并提供 Clear log 按钮。

Delete data on uninstall：卸载模块时删除本模块的设置和日志（订单中保存的 Ozow 数据会保留）。默认：off。

结账

在付款步骤，顾客选择付款方式（默认为 Instant EFT (Ozow)）并确认订单。模块会将顾客带到 Ozow 托管的付款页面，并附带一个以 ZAR 计的购物车总额的签名请求。银行对账单中的参考为 Cart 加购物车编号（最多 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.。如果被核查的付款之后失败，或未付款的订单被取消，则显示 Your Ozow payment was not completed. Please contact us about this order.。如果顾客返回时 Ozow 尚未确认付款，页面会显示等待文字，并带有 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.

如果购物车不是 ZAR，顾客会看到 Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

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

订单与退款

订单状态

暂无订单：顾客已被转到 Ozow，但尚未付款、已取消，或 Ozow 尚未确认付款。此时只存在购物车。

Payment accepted：付款已确认。订单消息会显示金额和 Ozow 交易 ID，以及付款是否已通过 GetTransaction API 确认。订单付款的交易 ID 即为 Ozow TransactionId。测试付款会收到消息 TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment：Ozow 或银行正在核查付款。Ozow 发送最终状态后，订单会更新。

Ozow payment on hold：订单消息会说明原因：已付金额或货币与购物车不符；订单已被取消后又收到了付款；或者在使用 API Key 时，GetTransaction API 尚无法确认付款或与之矛盾。请在 Ozow 后台核查付款，并更改订单状态。如果 API 无法响应，下一次 Ozow 通知会完成该订单。

付款错误：正在核查的付款被取消、被放弃或失败。之后针对该付款的成功 Ozow 响应仍会将订单标记为已付款。

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

Ozow 付款区块

订单页面会显示一个 Ozow payment 区块，包含交易参考和尝试次数、Ozow 交易 ID、状态、请求金额、Ozow 报告的金额、Ozow 消息，以及测试付款的 TEST MODE 标记。

退款

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

许可证密钥

本模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Ozow Pay 是 Modules > Module Manager > VibeFox Ozow Pay > Configure 页面上的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-payment-ozow 一行，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。

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

一个密钥只能用于一个域名：主店铺的域名，在多店铺配置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，结账时不会向顾客显示 Ozow。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已经开始的付款仍会被确认。

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

故障排除

结账时没有显示 Ozow：请检查许可证是否有效、Enable/Disable 是否开启、Site Code 和 Private Key 是否已填写，以及购物车货币是否为 ZAR。在 Payment > Preferences 中，检查该模块是否允许用于 ZAR、顾客所在国家以及顾客所在的客户组。缺少任何项目时，设置页面都会显示警告。

付款已完成，但未创建订单：Ozow 通知未能到达店铺，且顾客也没有返回。请检查您的店铺是否可以从互联网访问（没有阻止 Ozow 的密码保护或防火墙）。如果您的 Ozow 站点设置了固定 URL，请检查这些 URL 是否与 Payment notifications 中显示的完全一致。开启 Debug log，并在 Configure 页面查看日志。

通知返回 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 后台中的付款）。当同一购物车的顾客返回处理恰好在同一时刻进行时，或订单无法创建时，也会返回此响应；请查看日志。

测试付款未能支付订单：模块处于正式模式。在正式模式下，测试付款绝不会支付订单；订单消息或日志会说明这一点。

付款后订单处于 Ozow payment on hold：请阅读订单消息，并在 Ozow 后台核查付款，然后将订单设置为 Payment accepted，或在 Ozow 中退款。

卸载

进入 Modules > Module Manager，打开 VibeFox Ozow Pay 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果开启了 Delete data on uninstall，模块设置和日志会被删除。如果关闭，则所有设置都会保留，以便之后重新安装。Ozow 付款记录以及订单状态 Awaiting Ozow payment 和 Ozow payment on hold 始终会保留，因此重新安装后，对旧订单的延迟通知仍会被识别。现有订单会保留其付款消息和交易 ID。

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