VibeFox Nets Nexi for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 cURL 扩展。版本较旧的 PHP 或未启用 cURL 时，模块会拒绝安装。
Nets 账户：您需要 Nets Easy 账户的秘密密钥（测试和正式）。仅使用秘密密钥。无需结账密钥，因为顾客在 Nets 托管的付款页面上付款。
货币和付款方式：模块本身不限制货币或国家。请使用您的 Nets 账户中已启用的货币；不支持的货币会在创建付款时由 Nets 报告。顾客看到哪些付款方式取决于您的 Nets 合同、国家和货币。
Webhook 的 HTTPS：Nets 只会调用最多 256 个字符、且不含 "&" 的公共 HTTPS 地址，因此您的店铺需要 HTTPS 和友好网址才能接收 Webhook。若没有 Webhook，顾客返回店铺时或在订单页面进行状态检查时，付款仍会被确认。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Nets Nexi Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 从 Nets Easy 测试门户复制测试秘密密钥，并粘贴到 Test Secret Key 中（参见配置）。
5. 开启 Enable/Disable，保持 Test Mode 开启，点击 Save，然后下一笔测试订单。之后输入正式秘密密钥，并关闭 Test Mode。
安装时，模块会创建订单状态 Nets payment on hold。PrestaShop 只会把新的付款模块关联到安装时已启用的国家。请在 Payment > Preferences 中检查模块的货币、国家和顾客群组。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。在字段上方，页面会在所选模式的秘密密钥缺失时发出警告，例如 Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set.，并在测试模式开启时显示 Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged.
Nets Nexi（北欧）
部分标题会为所选模式显示 TEST 或 LIVE。
Enable/Disable：Enable Nets Nexi Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：结账时向顾客显示的付款方式标题。它也是订单中保存的付款方式名称。默认：Nets Easy。必填：标题留空会报错 Enter a title for the payment method.，且不会保存任何内容。
Description：结账时向顾客显示的付款方式描述。默认：Pay securely with Nets Easy。
API 密钥
从 Nets Easy 门户的 Company > Integration 中复制秘密密钥：测试密钥来自测试门户（test.portal.dibspayment.eu），正式密钥来自正式门户（portal.dibspayment.eu）。无需结账密钥。
Test Mode：测试模式使用 test.api.dibspayment.eu 和测试秘密密钥；正式模式使用 api.dibspayment.eu 和正式秘密密钥。订单的退款和扣款始终使用付款时所在的环境。默认：开启。开启时，顾客会在付款方式下方看到 Test mode: no real money will be charged.
Test Secret Key：您的 Nets 测试环境秘密 API 密钥。
Live Secret Key：您的 Nets 正式环境秘密 API 密钥。
已保存的密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved secrets：勾选某个密钥并点击 Save 即可删除。字段留空则保留已保存的值。
付款
Webhooks：Nets 通知（Webhook）会在每次付款时自动注册。无需在 Nets 门户中进行任何配置。该部分会显示通知发送的地址。使用友好网址时，地址类似 https://your-shop/module/wcp_nets_nexi_gateway/webhook，可能带有语言代码，如 /en/。如果地址不是公共 HTTPS 地址，该部分会警告店铺无法接收 Webhook；此时付款会在顾客返回店铺时确认，或通过订单页面上的 Nets: check payment status and capture: 确认。系统会注册以下事件：
每个 Webhook 都必须携带模块为该付款创建的随机秘密。没有正确秘密的 Webhook 会被拒绝。Webhook 仅告知模块哪笔付款发生了变化：付款本身始终使用付款所在环境的秘密密钥从 Nets API 读取。即使店铺处于维护模式，Webhook 也能正常工作，并且不会被店铺的国家限制阻止。
Order Status After Payment：Nets 确认并扣款后订单的状态。
高级
Debug log：将 API 调用和付款状态变化记录到模块文件夹中的 logs/nng_debug.log.php。该文件无法通过网页打开。错误始终会被记录。密钥和顾客数据不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete Data on Uninstall：卸载模块时删除模块设置和日志。保存在订单上的付款数据始终保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Nets Easy）并确认。模块会以购物车货币为购物车总额创建 Nets 付款，并将商品、运费、礼品包装和折扣作为订单行提交，然后将顾客引导至 Nets 托管的付款页面。Nets 中的付款参考为购物车编号。顾客的电子邮件、姓名、地址和电话在 Nets 接受其格式时会传递给 Nets。您结账的条款和条件页面会链接在 Nets 页面上（如未设置，则链接店铺首页）。此时尚未创建订单。
付款后，顾客返回您的店铺。只有在 Nets 确认后，订单才会被标记为已付款：模块从 Nets API 读取付款信息，将预授权金额和货币与购物车进行比对，扣款后才创建订单。这会在 Webhook 或顾客返回时发生，以先到者为准。随后顾客会看到标准的订单确认页面。如果付款尚无法确认（Nets 无法访问，或当时另一个请求正在确认），Payment confirmation 页面会显示 Your Nets payment is being confirmed. Your order will be created as soon as it is confirmed — please do not pay again.，并提供 Check again 和 Back to checkout 按钮。
如果顾客在 Nets 页面取消，会返回结账页面，并显示 The Nets payment was cancelled. You can try again or choose another payment method. 如果未付任何款项，消息为 The payment was not completed. You can try again or choose another payment method. 购物车会被保留。重新尝试时，模块会先检查之前的付款；如果已付款，则创建订单，而不是新建付款。否则，会先关闭之前的 Nets 会话，再开始新的会话。
如果 Nets 无法开始付款，顾客会停留在结账页面并看到简短提示，例如 Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method.、This payment method is temporarily unavailable. Please choose another payment method. 或 The payment service could not be reached. Please try again in a moment. 购物车总额为零时显示 The order total must be greater than zero to pay with Nets. 详细信息会写入日志。
模块仅使用托管付款页面。没有页面内嵌的 Nets 结账、订阅或定期付款、保存银行卡、发票费用、仅授权模式或按发货分次扣款。
订单与退款
订单状态
No order yet：顾客已被引导至 Nets 但尚未付款，或付款尚未确认。目前只存在购物车。
Payment accepted or Delivered：Nets 已确认并扣款。状态遵循 Order Status After Payment。付款会以 Nets 付款 ID 作为交易 ID 记录，备注中会显示付款 ID、扣款 ID 和付款方式。
Nets payment on hold：Nets 中的金额或货币与购物车不符（未扣款），扣款被拒绝，或顾客在订单取消后付款（已预授权，未扣款）。备注会说明原因。不会自动扣款。检查订单后，请使用 Nets: check payment status and capture: 扣款，或在 Nets 门户中取消预授权。
Canceled：处于暂停状态的订单的预授权已被取消，例如在 Nets 门户中取消。
Refunded：付款已通过模块全额退款。
重复的 Webhook 和页面刷新永远不会重复扣款或添加重复备注，已付款的订单也永远不会因 Nets 事件而再次更改。如果针对已付款订单完成了旧的付款链接，第二笔预授权会被自动释放；如果已经扣款，备注会提示您在 Nets 门户中退款。
Nets Easy 付款区块
订单页面会显示 Nets Easy payment 区块，包括付款 ID、扣款 ID、环境（测试付款会显示 Test environment 标记）、状态、Nets 中预授权和扣款的金额、订单总额和已退款金额、退款记录，以及订单的 Nets notes。该区块的按钮对所有有权编辑订单的员工都可用；无需访问模块页面。
Nets: check payment status and capture:显示在尚未付款的订单上。它会从 Nets 读取付款信息，并扣款与订单相符的预授权，包括扣款失败后或您检查暂停订单之后。如果没有任何变化，备注会说明原因，例如顾客尚未完成付款。
退款
在 Nets Easy payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Nets。确认提示 Refund this amount through Nets? This cannot be undone. 全额和部分退款在付款扣款后均受支持；仅预授权的付款可在 Nets 门户中取消。退款会针对订单在付款所在环境中的扣款进行。如果 Nets 不接受退款，区块会显示错误，且不会记录退款。成功的退款会连同 Nets 退款 ID 添加到退款记录和备注中。全额退款会将订单设为 Refunded；部分退款不会更改状态。
模块不会创建退款凭证。PrestaShop 订单页面上的标准退款按钮不会通过 Nets 退回款项。在 Nets 门户中进行的退款不会同步；如有需要，请手动更新订单。
许可证密钥
模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Nets Nexi Gateway 许可证区块位于 Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure 页面的顶部，在设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-payment-nets-nexi 一行，以及 Manage licenses and domains in your account 链接，可打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工可以更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。店铺地址变更后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺配置中同样如此。从店铺中移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Nets。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也仍然有效。
许可证到期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
Nets Nexi 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及所选模式是否设有秘密密钥：测试模式需要 Test Secret Key，正式模式需要 Live Secret Key。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许购物车货币、顾客所在国家以及顾客群组。
付款已完成，但没有创建订单：Webhook 未能到达您的店铺。请检查店铺是否使用 HTTPS 和友好网址，使 Webhooks 中的地址为不含 "&" 的公共 HTTPS 地址，并且已设置付款环境的秘密密钥。顾客付款后返回店铺时，订单也会被创建。
Webhook 返回 Unauthorized：Webhook 未携带该付款的秘密。Webhook 只接受与付款一同注册的秘密。
Webhook 返回 Busy, retry later、Payment lookup failed 或 Payment not reserved yet：另一个请求正在确认同一购物车，Nets API 无法访问，或预授权尚未可见。Nets 会自动重试 Webhook。
Webhook 返回 Order could not be created, retry later：无法创建订单，例如模块已被禁用。请开启 Debug log 以查看原因。
Webhook 网址在浏览器中显示 Method not allowed：这是正常现象。该地址只接受来自 Nets 的请求。
顾客在选择 Nets 时看到错误：请开启 Debug log，并查看模块页面上的 Log 字段。This payment method is temporarily unavailable. Please choose another payment method. 通常表示秘密密钥错误或缺失。被拒绝的货币会由 Nets 记录在日志中。
付款后订单处于 Nets payment on hold：请阅读区块中的 Nets notes。如果扣款被拒绝，请使用 Nets: check payment status and capture: 重试，或在 Nets 门户中扣款。如果金额或货币不一致，请在 Nets 门户中检查付款。如果顾客在取消后付款，请检查订单，并扣款或取消预授权。
Refund via Nets 缺失或失败：只有付款扣款后才能退款；此时区块会显示扣款 ID。退款使用订单付款所在环境的秘密密钥，因此必须设置该密钥；否则区块会说明缺少哪个环境的密钥。
卸载
进入 Modules > Module Manager，打开 VibeFox Nets Nexi Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单中的 Nets 付款数据（付款、扣款和退款）以及订单状态 Nets payment on hold 始终保留，因此之前已付款的订单即使在重新安装后也可以退款。现有订单会保留其付款备注和交易 ID。
Nets、Nets Easy 和 Nexi 是各自所有者的商标。本模块与 Nets 或 Nexi 没有关联，也未获其认可。