VibeFox Netopia for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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 购买。一个密钥只能用于一个域名。

安装

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

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

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

4. 在 Netopia 后台打开您的销售点，复制账户签名，并下载沙盒和正式环境的证书和私钥。将签名和文件的完整内容粘贴到设置中（参见“配置”）。

5. 启用 Enable/Disable 并点击 Save。先在沙盒模式下测试付款，然后关闭 Test mode 以接收真实付款。

安装时，模块会创建两个订单状态：Awaiting Netopia payment 和 Netopia payment on hold。PrestaShop 会为所有货币、国家和顾客群组提供一个新的付款模块。您可以在 Payment > Preferences 中进行限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Netopia Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果当前环境缺少账户签名、证书或私钥，页面会发出警告（此时结账时会隐藏该付款方式），并且在测试模式开启时显示 Test mode is on: payments go to the Netopia sandbox and no real money is charged.。保存时，无效的证书或私钥会被拒绝并显示错误，并保留之前的值；其他字段仍会保存。

IPN (confirm) URL

该 URL 显示在页面顶部，为只读。启用友好 URL 时，它的形式类似 https://your-shop/module/wcp_netopia_gateway/notify，可能还带有语言代码，例如 /en/。它会随每个付款请求作为确认 URL 发送，因此您无需在 Netopia 后台中输入它。Netopia 会将 IPN 发送到该 URL。模块使用付款发起所在环境的私钥解密 IPN，并检查您的账户签名和付款请求。Netopia 会报告以下操作：

带有 Netopia 错误代码的通知（例如银行卡被拒）会将等待中的订单设为 Payment error；如果没有订单，顾客可以重新付款。无法解密、带有其他账户签名或不对应该购物车付款请求的通知会被拒绝，并且不会更改任何内容。

结账

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

Title：结账时显示的付款方式标题。它也是订单中保存的付款方式名称。默认：Card Payment (Netopia)。

Description：结账时显示的付款方式说明。默认：Pay securely with your credit or debit card via Netopia.

Netopia 账户

在 Netopia 后台进入 Seller accounts > your point of sale > Technical settings：复制账户签名，并下载每个环境的公钥证书（.cer）和私钥（.key）。用文本编辑器打开文件，并粘贴其全部内容，包括 BEGIN/END 行。

Account signature：卖家账户签名（格式为 XXXX-XXXX-XXXX-XXXX-XXXX），沙盒和正式环境使用相同的签名。

Test mode：使用 Netopia 沙盒（sandboxsecure.mobilpay.ro）和沙盒密钥。默认：on。关闭它即可使用正式密钥接收真实付款。

Sandbox public certificate (.cer)：沙盒公钥证书文件的内容。用于加密付款请求。

Sandbox private key (.key)：沙盒私钥文件的内容。用于解密 IPN。

Live public certificate (.cer)：正式环境公钥证书文件的内容。

Live private key (.key)：正式环境私钥文件的内容。

已保存的私钥不会再次显示。该字段保持为空，其帮助文本以 A private key is saved. 开头。若要保留已保存的密钥，请将字段留空；若要替换，请粘贴新密钥。证书字段留空则会删除证书。

Clear saved private keys：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的密钥。

订单

Order status after payment：已付款订单的状态。

高级

Debug log：将请求和 IPN 处理过程写入模块文件夹中的 logs/netopia_p_debug.log.php。该文件无法通过网页打开。不会记录银行卡数据、密钥或顾客信息。错误（例如被拒绝的 IPN）即使在该选项关闭时也始终会被记录。默认：off。

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

Delete data on uninstall：卸载模块时，删除网关设置、模块的 Netopia 付款记录和日志。订单会保留。默认：off。

结账

在付款步骤中，顾客选择付款方式（默认为 Card Payment (Netopia)）并确认。下一页会显示 Redirecting you to Netopia for secure payment…，并自动将顾客引导至 Netopia 付款页面；备用按钮为 Proceed to payment 和 Cancel（返回结账页面）。付款请求使用您的 Netopia 证书加密，包含以购物车货币表示的购物车总额、带有购物车编号的 Cart #，以及账单和配送联系信息。在沙盒模式下，请求会发送到 Netopia 沙盒。此时尚不存在订单。

顾客在 Netopia 页面使用银行卡付款后返回您的店铺。返回本身绝不会创建或支付订单。只有在 Netopia 通过 IPN 确认后，订单才会被标记为已付款。如果订单已存在，顾客会看到标准的订单确认页面。对于等待中的订单，页面显示 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.。购物车会保留。每次新的尝试都会生成新的付款请求；该购物车之前的请求仍然有效，因此较早尝试的延迟 IPN 仍会被记录。

如果模块配置不正确，顾客会停留在结账页面，并显示 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 仍然可以工作，并且不会受到店铺国家限制的阻止。

本模块仅通过 Netopia v1 银行卡协议接受银行卡付款。不支持通过 PrestaShop 进行退款或扣款，不支持保存银行卡或一键付款，不支持订阅、分期付款或其他付款方式，也不支持 Netopia API v2。

订单和退款

订单状态

尚无订单：顾客已被引导至 Netopia 但尚未付款，或 Netopia 尚未发送 IPN。此时只存在购物车。

Payment accepted or Delivered：Netopia 已确认付款。状态遵循 Order status after payment。付款会以 Netopia 交易作为交易 ID 记录，私人备注会显示金额、隐藏部分卡号以及 Netopia 交易；沙盒付款会标记为 [sandbox]。

Awaiting Netopia payment：该付款是等待在 Netopia 后台扣款的预授权，或正在 Netopia 审核中。尚未记录任何付款。Netopia 确认后，订单会转为已付款状态。

Netopia payment on hold：账单金额或货币与购物车或订单不一致，付款仅部分扣款，Netopia 确认了已取消订单或使用其他付款方式的订单的付款，或者在店铺处于正式模式时确认了沙盒（测试）付款（未收到真实款项，因此不记录付款）。备注会说明原因。请在 Netopia 后台核对交易，然后处理订单或在那里退款。

Payment error：对于等待中的订单，Netopia 报告了错误，例如银行卡被拒。

Canceled：Netopia 已取消等待中订单的付款。

Refunded：付款已在 Netopia 后台全额退款。

延迟通知绝不会降低已付款或已关闭订单的状态。如果 Netopia 为已付款的订单确认了另一笔付款，备注会提示您在 Netopia 后台退还重复付款。

Netopia 区块

订单页面会显示 Netopia Payments 区块，包括 Netopia 交易、环境（沙盒或正式）、付款请求、最后一次 IPN 操作、隐藏部分卡号、已付款、已退款和剩余金额，以及退款记录。该区块为只读。

退款

退款不能通过 PrestaShop 进行：Netopia v1 银行卡协议没有退款接口。请在 Netopia 后台对交易进行退款。随后 Netopia 会发送一个贷记 IPN，模块会自动将退款记录在订单上，并附带备注 Netopia refund processed: 和金额。部分退款会保持订单状态；当没有剩余可退款金额时，订单会被设为 Refunded。对于 EUR、USD 和 GBP 订单，Netopia 以 RON 报告的退款金额会换算回订单货币。退款绝不会重复记录，也绝不会超过剩余金额。如果 Netopia 报告退款错误，则只会添加一条备注。

本模块不会开具退款单，也不会将商品退回库存。订单页面上的 PrestaShop 标准退款按钮不会通过 Netopia 退回款项。

许可证密钥

本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Netopia Gateway 许可证区块是 Modules > Module Manager > VibeFox Netopia Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 字段中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方有 Product: presta-payment-netopia 一行，以及打开您 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 账户中释放该名额。

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

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

故障排除

结账时不显示 Netopia：请检查许可证是否有效、Enable/Disable 是否已开启、当前环境是否配置完整（测试模式下需要沙盒的 Account signature、证书和私钥，正式模式下需要正式环境的这些项目），以及购物车货币是否为 RON、EUR、USD 或 GBP。缺少任何内容时，设置页面都会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车货币、顾客所在国家和顾客群组。

付款已完成，但没有创建订单：IPN 未到达您的店铺，或被拒绝。请检查设置中的 IPN（确认）URL 是否可以从互联网访问（没有基本身份验证或防火墙阻拦）。查看模块页面上的 Log 字段：被拒绝的 IPN 始终会被记录。开启 Debug log 可查看每一条 IPN。仅靠顾客返回页面绝不会创建订单。

日志显示 failed decrypting data：私钥与 Netopia 使用的证书不匹配。IPN 会使用每个环境中已保存的私钥进行解密，因此在另一环境的付款仍未完成时，请保留其已保存的密钥。Netopia 会重试 IPN。

日志显示 signature mismatch：Account signature 与发送 IPN 的销售点不一致。请从 Netopia 后台重新复制。

日志显示 unknown payment request：该 IPN 不对应您的店铺为该购物车在该环境（沙盒或正式）中发出的任何付款请求。不会更改任何内容。

日志显示 gateway not configured：没有保存私钥或账户签名。Netopia 会重试 IPN，设置完成后付款将被记录。

日志显示 busy, retry later or processing failed：该购物车在同一时刻正被另一个请求处理，或者订单无法创建（例如模块已被禁用）。Netopia 会自动重试 IPN。

保存证书或私钥时出错：粘贴的文本不是有效的证书或密钥。请粘贴完整的文件内容，包括 BEGIN/END 行。之前的值已保留。

付款后订单处于 Netopia payment on hold：请阅读订单的私人备注（参见“订单状态”）。金额或货币不一致，仅部分扣款，订单已被取消，或者在店铺处于正式模式时确认了沙盒付款。请在 Netopia 后台核对交易。

在 Netopia 中进行的退款没有显示在订单上：贷记 IPN 未到达店铺或被拒绝。请检查日志。

卸载

进入 Modules > Module Manager，打开 VibeFox Netopia Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，则会删除网关设置（包括已保存的密钥）、模块的 Netopia 付款记录（显示在订单的 Netopia 区块中）和日志。如果已关闭，则所有内容都会保留，以便日后重新安装。订单以及 Awaiting Netopia payment 和 Netopia payment on hold 这两个订单状态永远不会被删除。现有订单会保留其付款备注和交易 ID。

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