VibeFox Netopia for OpenCart — 帮助
系统要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本，并需启用 OpenSSL、DOM 和 SimpleXML 扩展。
货币: 顾客必须以 RON、EUR、USD 或 GBP 结账。EUR、USD 和 GBP 必须在您的 Netopia 账户中启用。对于其他货币，结账时将隐藏该付款方式。订单以其自身货币扣款。
Netopia 账户: 您需要一个带有销售点的 Netopia Payments 卖家账户。从其技术设置中，您需要账户签名，以及您所使用的每个环境（沙盒和正式）的公钥证书（.cer）和私钥（.key）。Netopia 端无需进行任何设置：每次付款请求时都会发送 IPN 地址。
公开店铺: IPN（确认）URL 必须能够从互联网访问，不得位于登录、基本身份验证或防火墙之后。订单只会通过 Netopia IPN 获得状态。
VibeFox 许可证密钥: 在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_netopia_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_netopia_gateway.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。许可证密钥对两个版本通用。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_netopia_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Netopia Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要具有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见 License key）。
4. 在 Netopia 管理后台中打开您的销售点，复制账户签名，并下载沙盒环境和正式环境的证书与私钥。将签名以及文件的完整内容粘贴到设置中（参见 Configuration）。
5. 开启 Enable/Disable，然后点击 Save。在沙盒模式下测试一笔付款，然后关闭 Test mode 以接受真实付款。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_netopia_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments，找到 VibeFox Netopia Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥、账户签名、证书和私钥。两个版本的设置页面及其字段相同。只有 IPN URL 不同（参见 Configuration）。
新安装时，该付款方式默认关闭，测试模式默认开启。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Netopia Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果当前有效环境缺少账户签名、证书或私钥，页面会发出警告（此时该付款方式会在结账时隐藏）；测试模式开启时，页面会显示 Test mode is on: payments go to the Netopia sandbox and no real money is charged. 如果没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 最多可包含 128 个字符，Sort order 必须为整数（允许负数），Minimum total 必须为大于或等于 0 的数字，并且地理区域和订单状态必须存在；如果其中任何一项有误，则不会保存任何内容。无效的证书或私钥会以红色错误提示被拒绝，并保留之前的值，而其他字段仍会保存（Settings saved, except the values shown in red.）。如果启用了该付款方式，但当前有效环境不完整，保存时会显示警告。
IPN（确认）URL
第一部分以只读方式显示 IPN (confirm) URL。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_netopia_gateway/notify，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_netopia_gateway/payment/wcp_netopia_gateway.notify，由您的 OpenCart 安装的店铺前台地址生成。它会在每次付款请求中作为确认 URL 发送，因此您无需在 Netopia 管理后台中输入它。Netopia 会将 IPN 发送到该 URL。扩展使用发起付款的环境的私钥对其解密，并检查您的账户签名和付款请求。Netopia 报告以下操作：
带有 Netopia 错误代码的通知（例如银行卡被拒）会将待处理的订单设为付款错误状态；无状态的订单保持无状态，顾客可以再次付款。无法解密、带有其他账户签名或未响应该环境中该订单付款请求的通知会被拒绝，且不会更改任何内容。即使您关闭该付款方式，已发起付款的通知仍会被接受。
Checkout
Enable/Disable: Enable Netopia Payments 用于开启或关闭该付款方式。默认：关闭。
Title: 结账时显示的付款方式标题。它也是订单中保存的付款方式名称。最多 128 个字符；留空则使用默认值。默认：Card Payment (Netopia)。
Description: 在 Confirm Order 步骤中显示给顾客的文字。默认：Pay securely with your credit or debit card via Netopia.
Sort order: Netopia 在结账付款方式中的位置。留空或输入整数。
Geo zone: 仅对所选地理区域内的付款地址提供 Netopia。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Minimum total: 订单须达到的、以店铺默认货币计算的总金额，达到后才会提供 Netopia。留空则没有最低金额要求。
Netopia 账户
在 Netopia 管理后台中进入 Seller accounts > your point of sale > Technical settings：复制账户签名，并下载每个环境的公钥证书（.cer）和私钥（.key）。用文本编辑器打开这些文件，并粘贴其完整内容，包括 BEGIN/END 行。该部分链接到 Netopia v1 文档。
Account signature: 卖家账户签名（格式为 XXXX-XXXX-XXXX-XXXX-XXXX），沙盒和正式环境相同。
Test mode: 使用 Netopia 沙盒（sandboxsecure.mobilpay.ro）及沙盒密钥。默认：开启。关闭后将使用正式密钥（secure.mobilpay.ro）接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode (Netopia sandbox): no real money is charged.
Sandbox public certificate (.cer): 沙盒公钥证书文件的内容。用于加密付款请求。
Sandbox private key (.key): 沙盒私钥文件的内容。用于解密 IPN。
Live public certificate (.cer): 正式公钥证书文件的内容。
Live private key (.key): 正式私钥文件的内容。
已保存的私钥不会再次显示。该字段保持为空，其帮助文字以 A private key is saved. 开头。若要保留已保存的密钥，请将字段留空；若要替换，请粘贴新的密钥。要删除已保存的私钥，请勾选字段下方的 Clear the saved private key on save，然后点击 Save。证书字段留空则会删除证书。
订单
OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Netopia 报告付款后，订单才会获得状态。OpenCart 没有自己的 Netopia 订单状态，因此下面的每个字段都列出了您的 OpenCart 订单状态。订单中的备注会说明每一次变更。
Order status after payment: 已付款订单的状态。
Processing status: 默认：处理中。
Completed status: 默认：已完成。
Awaiting Netopia payment: 等待在 Netopia 管理后台进行捕获的预授权，或在 Netopia 审核中的付款。默认：待处理。
Netopia payment on hold: 该付款需要您审核（参见 Order statuses）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。即使“待处理”与“暂停”使用相同的状态，扩展也会将这两种情况区分开。
Canceled status: Netopia 取消了待处理订单的付款。默认：已取消。
Payment error status: 对于待处理的订单，Netopia 报告了错误（例如银行卡被拒）。默认：失败。
Refunded status: 在 Netopia 管理后台完成退款后，已无可退金额。默认：已退款。
高级
Debug log: 将请求和 IPN 处理过程写入 OpenCart 日志文件夹（storage/logs）中的 netopia_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 netopia_p_debug.old.log.php。银行卡数据、密钥和顾客信息不会被记录。错误（例如被拒绝的 IPN）即使在该选项关闭时也始终会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall: 开启时，卸载扩展会删除网关设置和日志。订单和 Netopia 付款记录始终会保留。默认：关闭。
导入 / 导出
Export: Download JSON 将设置（包括证书）保存为 JSON 文件。私钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的私钥会被保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 Card Payment (Netopia)）。在 Confirm Order 步骤中，顾客会看到您的描述以及说明 You will be redirected to the Netopia secure page to pay with your card. OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会构建付款请求，使用当前有效环境的 Netopia 证书进行加密，并将顾客直接带到 Netopia 付款页面。该请求包含以订单货币表示的订单总额、带有订单号的 Order #，以及附带订单电话的账单和配送联系信息。在沙盒模式下，请求会发送到 Netopia 沙盒。在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。
顾客在 Netopia 页面上用银行卡付款，然后返回您的店铺。返回操作本身从不会为订单付款。只有在 Netopia 通过 IPN 确认后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。对于待处理的订单，页面会显示 Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. 对于暂停中的订单，页面会显示 Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. 当待处理或暂停的订单稍后获得最终状态（已付款、付款错误或已取消）时，顾客会收到一封包含新状态的邮件。对于已取消的订单，页面会显示 The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. 对于付款错误的订单，页面会显示 The payment was declined by Netopia.
如果顾客返回时 IPN 尚未到达，Payment confirmation 页面会显示相同的“尚未确认”文字，并提供 Check again 和 Back to checkout 按钮。IPN 一到达，订单就会获得状态。
如果 Netopia 报告某个无状态订单被取消或被拒绝，顾客会返回结账页面，并看到 The payment was cancelled at Netopia. You can try again or choose another payment method. 或 The payment was declined by Netopia. You can try again or choose another payment method. 在 OpenCart 4 中，这些消息会显示在结账页面上方。购物车会被保留。每次新的尝试都会生成新的付款请求；之前的请求仍然有效，因此较早尝试的延迟 IPN 仍会被记录。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则为结账保留一个订单，并通过新的付款请求再次为同一订单付款；如果同一购物车的另一笔订单已付款、待处理或暂停，顾客会进入成功页面，并且不会发起新的付款。
OpenCart 4 会在显示成功页面之前将订单保留在结账流程中。如果该订单期间在未付款的情况下被关闭（例如其预授权被取消、在待处理后被拒绝，或您取消或退款了该订单），顾客会被带回结账页面，并看到 Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 将为新订单付款。已付款后又被取消或退款的同一购物车订单不再占用该购物车。
如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条消息：Netopia gateway is not configured properly. Please contact the store administrator.、Netopia cannot process payments in 加上货币、This order has nothing to pay. 或 Payment encryption failed. Please try again or contact support. 技术原因会写入日志。
即使店铺处于维护模式，IPN 仍然有效，因为 OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展为此添加了一个启动动作（startup action），这也允许顾客从 Netopia 返回。
该扩展仅通过 Netopia v1 银行卡协议接受银行卡付款。它不支持从 OpenCart 进行退款或捕获，不支持保存银行卡或一键付款，不支持订阅、分期付款或其他付款方式，也不支持 Netopia API v2。
订单和退款
Order statuses
No status (missing order): 顾客已被转到 Netopia 但尚未付款，Netopia 尚未发送 IPN，或付款在任何结果出现之前已被取消或拒绝。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时，才会显示此类订单。
Processing or Completed status: Netopia 已确认付款。状态遵循 Order status after payment。备注中会显示金额、被遮盖的银行卡号以及 Netopia 交易；沙盒付款会标记为 [sandbox]。
Awaiting Netopia payment: 付款是等待在 Netopia 管理后台捕获的预授权，或正在 Netopia 审核。Netopia 确认后，订单会转为已付款状态。
Netopia payment on hold: 发票金额或货币与订单不同，只捕获了部分付款，Netopia 确认了已取消订单或以其他付款方式下的订单的付款，或者在店铺处于正式模式时确认了沙盒（测试）付款（未收到任何真实资金）。订单不会被标记为已付款；备注会说明原因。请在 Netopia 管理后台检查该交易，然后处理订单或在那里退款。
Payment error status: 对于待处理的订单，Netopia 报告了错误，例如银行卡被拒。
Canceled status: Netopia 取消了待处理订单的付款。
Refunded status: 付款已在 Netopia 管理后台全额退款。
延迟通知从不会降低已付款或已关闭订单的状态。如果 Netopia 为已付款的订单确认了另一笔付款，备注会提示您在 Netopia 管理后台退还重复的款项。如果顾客为同一购物车支付了第二笔订单，该订单会保持无状态，并且付款请求会被标记为该购物车的重复付款。
备注是订单 History 中的条目，顾客看不到。
VibeFox Netopia Gateway 选项卡
在 Sales > Orders 中打开一个通过 Netopia 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Netopia Gateway 选项卡会显示 Netopia Payments 区块：Netopia 交易、环境（沙盒或正式）、付款请求、请求状态、最近一次 IPN 操作、被遮盖的银行卡、已付款、已退款及剩余金额、退款历史，以及该订单的 Netopia notes。该选项卡为只读，并且显示给有权访问该扩展的用户。
退款
退款和捕获无法从 OpenCart 执行：Netopia v1 银行卡协议没有退款调用。请在 Netopia 管理后台对交易进行退款。随后 Netopia 会发送一个贷记 IPN，扩展会自动将退款记录到订单中，并附上备注 Netopia refund processed: 和金额。部分退款会保留订单状态；当没有剩余可退金额时，订单会被设为 Refunded status。对于 EUR、USD 和 GBP 订单，Netopia 以 RON 报告的退款金额会换算回订单货币。退款绝不会被重复记录，也绝不会超过剩余金额。如果 Netopia 报告退款错误，则只会添加一条备注。
在 Sales > Returns 中的商品退货不会通过 Netopia 退款。
许可证密钥
该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥才能运行。License — VibeFox Netopia Gateway 许可证区块位于 Extensions > Extensions > Payments > VibeFox Netopia Gateway > Edit 的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方有一行 Product: opencart-payment-netopia，以及打开您 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。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。
一个密钥只能用于一个域名。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 Netopia。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，该付款方式对所有人都会隐藏。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，在 Netopia 管理后台所做的退款仍会被记录。
许可证过期后，扩展仍会继续运行，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
Netopia does not appear at checkout: 检查许可证是否有效、Enable/Disable 是否开启、当前有效环境是否完整（测试模式下需要 Account signature 以及沙盒的证书和私钥，正式模式下需要正式环境的这些内容），以及顾客是否使用 RON、EUR、USD 或 GBP 结账。缺少任何内容时，设置页面会显示警告。还需检查付款地址是否位于所选的 Geo zone 中，以及订单是否达到 Minimum total。
The payment went through, but the order stays without a status: IPN 未能到达您的店铺，或已被拒绝。请检查设置中的 IPN（确认）URL 是否可以从互联网访问（不得有基本身份验证或防火墙）。查看扩展页面上的 Log 字段：被拒绝的 IPN 始终会被记录。开启 Debug log 可查看每一条 IPN。顾客的返回本身永远不会为订单付款。
Log shows failed decrypting data: 私钥与 Netopia 所用的证书不匹配。IPN 使用每个环境已保存的私钥进行解密，因此在另一环境的付款仍未完成时，请保留该环境的密钥。Netopia 会重试 IPN。
Log shows signature mismatch: Account signature 与发送该 IPN 的销售点不一致。请从 Netopia 管理后台重新复制。
Log shows unknown payment request: 该 IPN 与您的店铺在该环境（沙盒或正式）为该订单发出的任何付款请求都不对应。不会更改任何内容。
Log shows gateway not configured: 未保存私钥或账户签名。Netopia 会重试 IPN，待设置完整后，该付款会被记录。
Log shows busy, retry later or processing failed: 购物车在同一时刻正被另一个请求处理，或无法设置订单状态。Netopia 会自动重试 IPN。
Error on save about the certificate or private key: 粘贴的文本不是有效的证书或密钥。请粘贴包括 BEGIN/END 行在内的完整文件内容。之前的值已被保留。
The customer sees This payment method is not available. Please reload the checkout page.: 结账会话已与订单不再匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。
Order is in the on-hold status after payment: 阅读 VibeFox Netopia Gateway 选项卡中的备注（参见 Order statuses）。金额或货币不一致、仅捕获了部分款项、订单已被取消，或店铺处于正式模式时确认了沙盒付款。请在 Netopia 管理后台检查该交易。
A refund made in Netopia does not appear on the order: 贷记 IPN 未能到达店铺，或已被拒绝。请检查日志。
面向开发者：可通过 OpenCart 事件 netopia_p_supported_currencies 更改可接受的货币列表。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Netopia Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort order、Geo zone、Minimum total，以及 Orders 部分的 OpenCart 订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件和在维护模式下放行 IPN 的启动动作）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、描述、账户签名、测试模式、证书、私钥、付款后订单状态、日志记录）和日志都会被删除。如果未开启，这些内容将被保留，以供日后重新安装使用。Netopia 付款记录始终会保留，因此在重新安装之前发起的付款，其延迟的 IPN 仍能找到对应订单。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Netopia Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Netopia Payments 和 mobilPay 是其各自所有者的商标。本扩展与 Netopia Payments 没有关联，也未获得 Netopia Payments 的认可。