VibeFox Netopia for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。
PHP：8.0 或更高版本，并启用 OpenSSL 和 DOM 扩展。
货币：店铺或订单货币必须为 RON、EUR、USD 或 GBP。EUR、USD 和 GBP 必须在您的 Netopia 账户中启用。对于其他货币，结账时会隐藏该付款方式。
Netopia 账户：您需要一个带销售点的 Netopia Payments 卖家账户。从其技术设置中获取账户签名，并且对于您使用的每个环境（沙盒和正式环境），获取公钥证书（.cer）和私钥（.key）。Netopia 端无需进行任何设置：每次付款请求都会附带 IPN 地址。
公开网站：IPN（确认）URL 必须可从互联网访问，不能位于登录、基本身份验证或维护页面之后。订单仅通过 Netopia IPN 更新。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_netopia_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Netopia Payments > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 在 Netopia 管理后台中打开您的销售点，复制账户签名，并下载沙盒和正式环境的证书与私钥。将签名和文件的完整内容粘贴到设置中（参见配置）。
6. 开启 Enable/Disable。在沙盒模式下测试一次付款，然后取消勾选 Test mode 以接受真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > Netopia Payments。在字段上方，如果当前环境缺少账户签名、证书或私钥，页面会发出警告（此时该付款方式会在结账时隐藏）；测试模式开启时，页面会显示 Test mode is on: payments go to the Netopia sandbox and no real money is charged.。在付款方式列表中，在所选环境配置完成之前，Netopia 会被标记为需要设置。保存时，无效的证书或私钥会被拒绝并显示错误，同时保留之前的值。
IPN (confirm) URL
显示在设置顶部，为只读。格式类似 https://your-site/wc-api/netopia_payment_callback/。它会作为确认 URL 随每个付款请求发送，因此您无需在 Netopia 管理后台中输入它。Netopia 会将 IPN 发送到此 URL；插件使用当前环境的私钥解密该通知，并检查您的账户签名和付款请求。Netopia 会报告以下操作：
带有 Netopia 错误代码的通知（例如银行卡被拒）会将未付款订单标记为 Failed。无法解密、带有其他账户签名或不对应该订单付款请求的通知会被拒绝，且不会更改任何内容。
结账
Enable/Disable：Enable Netopia Payments 用于开启或关闭该付款方式。默认：关闭。
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：Use the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys。用于切换付款页面和密钥对。默认：开启。关闭后将使用正式密钥接受真实付款。
Sandbox public certificate (.cer)：沙盒公钥证书文件的内容。用于加密付款请求。
Sandbox private key (.key)：沙盒私钥文件的内容。用于解密 IPN。保存后不会再次显示；该字段会显示 A private key is saved.。如需保留已保存的密钥，请留空；如需替换，请粘贴新密钥。
Live public certificate (.cer)：正式环境公钥证书文件的内容。
Live private key (.key)：正式环境私钥文件的内容。保存后不会再次显示；如需保留已保存的密钥，请留空。
订单
Order status after payment：需要发货的已付款订单的状态。仅包含虚拟或可下载商品的订单无论如何都会由 WooCommerce 直接完成。该状态通过一次状态变更设置，并且只向顾客发送一封邮件。
高级
Debug log：Log requests and IPN processing 会写入 WooCommerce > Status > Logs，来源为 wcp_netopia_gateway。银行卡数据、密钥和顾客信息不会被记录。错误（例如被拒绝的 IPN）即使在该选项关闭时也始终会被记录。默认：关闭。
Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted (orders are kept)。默认：关闭。
结账
顾客选择付款方式（默认为 Card Payment (Netopia)）并下单。下一页会显示 Redirecting you to Netopia for secure payment…，并自动将顾客带到 Netopia 付款页面；备用按钮为 Proceed to payment 和 Cancel order。付款请求使用您的 Netopia 证书加密，包含订单货币的订单总额、Order # 及订单号，以及账单和配送联系信息。在沙盒模式下，请求会发送到 Netopia 沙盒环境。
顾客在 Netopia 页面使用银行卡付款后，会返回您店铺的订单完成页面。仅仅返回本身不会将订单标记为已付款。只有在 Netopia 通过 IPN 确认后，订单才会被标记为已付款。在此之前，订单完成页面会显示 Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed.。对于 On hold 状态的订单，页面会显示 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.。
如果银行卡被拒绝，订单会被标记为 Failed，顾客可以从订单页面重新付款。如果插件配置不正确，付款页面会显示 Netopia gateway is not configured properly. Please contact the store administrator.。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce High-Performance Order Storage（HPOS）兼容。
插件仅通过 Netopia v1 银行卡协议接受银行卡付款。不支持通过 WooCommerce 进行退款或扣款，也不支持保存银行卡或一键付款、订阅、分期付款、短信、银行转账或加密货币付款，并且不支持 Netopia API v2。
订单和退款
订单状态
Pending payment：顾客已被转到 Netopia，或 Netopia 尚未发送 IPN。
Processing or Completed：Netopia 已确认付款。状态遵循 Order status after payment 设置。订单备注会显示金额、已隐藏部分的银行卡号以及 Netopia 交易；沙盒付款会标记为 [sandbox]。交易 ID 即为 Netopia 交易。
On hold：付款是等待在 Netopia 管理后台扣款的预授权，或正在 Netopia 审核中。Netopia 确认后，订单会被标记为已付款。当账单金额或货币与订单不符、仅部分付款被扣款，或 Netopia 确认了已取消订单的付款时，订单也会进入此状态。订单备注会说明原因。请在 Netopia 管理后台检查交易，并手动完成或退款该订单。
Failed：Netopia 报告了错误，例如银行卡被拒绝。顾客可以重新付款。
Cancelled：Netopia 取消了付款，或顾客在前往 Netopia 之前点击了 Cancel order。
延迟通知绝不会降低已付款订单的状态。如果 Netopia 为已付款的订单确认了另一笔付款，备注会提醒您在 Netopia 管理后台退还重复付款。
退款
退款无法通过 WooCommerce 完成：Netopia v1 银行卡协议没有退款接口，因此不存在 Refund via 按钮。请在 Netopia 管理后台对该交易进行退款。随后 Netopia 会发送一条贷记 IPN，插件会自动在订单上记录退款，原因为 Refund initiated by Netopia.。部分退款会保持订单状态不变；当没有可退款金额时，WooCommerce 会将订单标记为 Refunded。对于 EUR、USD 和 GBP 订单，Netopia 以 RON 报告的退款金额会换算回订单货币。退款绝不会重复记录，也不会超过剩余金额。库存不会自动恢复。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Netopia Payments 的顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证的有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放该域名的名额。请在您的 vibefox.net 账户中释放名额。
如果没有有效密钥，Netopia 不会在结账时向顾客显示。如果仍然开始付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，在 Netopia 管理后台完成的退款仍会被记录。
许可证到期后，插件会继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时未显示 Netopia：请检查许可证是否有效，Enable/Disable 是否开启，所选环境是否配置完整（测试模式下需要沙盒的 Account signature 以及证书和私钥，正式模式下需要正式环境的），以及店铺或订单货币是否为 RON、EUR、USD 或 GBP。设置页面在缺少内容时会显示警告。
付款已完成，但订单仍处于 Pending payment：IPN 未到达您的店铺或被拒绝。请检查设置中的 IPN（确认）URL 是否可从互联网访问（不处于维护模式，不受基本身份验证或防火墙限制）。开启 Debug log，并在 WooCommerce > Status > Logs 中查找来源为 wcp_netopia_gateway 的 IPN 记录。仅凭顾客的返回绝不会将订单标记为已付款。
Log shows failed decrypting data：私钥与 Netopia 所用环境的证书不匹配。IPN 会使用当前环境的密钥解密；对于在切换测试模式之前发起的付款，则使用另一环境的密钥解密。Netopia 会重试。
Log shows signature mismatch：Account signature 与发送 IPN 的销售点不一致。请从 Netopia 管理后台重新复制。
Log shows unknown payment request：该 IPN 不对应您店铺在该环境（沙盒或正式）中为此订单发出的付款请求。不会进行任何更改。
Log shows gateway not configured：缺少私钥或账户签名。Netopia 会重试 IPN，设置完成后付款将被记录一次。
Error on save about the certificate or private key：粘贴的文本不是有效的证书或密钥。请粘贴文件的完整内容，包括 BEGIN/END 行。已保留之前的值。
Order is On hold after payment：请阅读订单备注。付款可能是预授权或正在审核中，金额或货币可能不一致，可能只扣了部分款项，订单可能已被取消，或者在店铺处于正式模式时确认了沙盒付款（并未收到真实款项）。请在 Netopia 管理后台检查该交易。
A refund made in Netopia does not appear on the order：贷记 IPN 未到达店铺或被拒绝。请检查日志。如有需要，请在 WooCommerce 中创建手动退款。
The license block shows an error：请按照许可证区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用最后一次已知的状态运行。
卸载
停用插件会保留所有数据。要删除它，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。只有在开启了 Delete data on uninstall 的情况下，网关设置（包括已保存的密钥）和日志才会被删除。否则它们会保留，以便以后重新安装时使用。现有订单会保留其付款备注和交易 ID。
Netopia Payments 和 mobilPay 是其各自所有者的商标。本插件与 Netopia Payments 无关联，也未获得其认可。