VibeFox Nets Nexi for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Nets 账户：您需要 Nets Easy 账户的密钥（测试和正式）。仅使用密钥（secret key）。无需结账密钥（checkout key），因为顾客在 Nets 托管的支付页面上付款。

币种和支付方式：扩展本身不限制币种。请使用您的 Nets 账户中已启用的币种；如果币种不受支持，Nets 会在创建付款时报错。顾客能看到哪些支付方式取决于您与 Nets 的合同、国家和币种。

Webhook 需要 HTTPS：Nets 只会调用不超过 256 个字符且不含 "&" 的公共 HTTPS 地址，因此您的商店需要 HTTPS 才能接收 webhook。没有 HTTPS 时，顾客返回商店或在订单页面进行状态检查时，付款仍会被确认。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请将其解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_nets_nexi_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_nets_nexi_gateway.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_nets_nexi_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将此安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Nets Nexi Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。

4. 从 Nets Easy 测试门户复制测试密钥，并将其粘贴到 Test Secret Key 中（参见配置）。无需在 Nets 门户中进行任何设置。

5. 开启 Enable/Disable，保持 Test Mode 开启，点击 Save 并下一个测试订单。然后输入正式密钥，并关闭 Test Mode。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_nets_nexi_gateway.ocmod.zip。请不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Nets Nexi Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 步骤 3 至 5 的方法输入许可证密钥和机密密钥。两个版本的设置页面及其字段相同。只有 webhook 地址不同（参见 Webhooks）。

新安装时，支付方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit。各部分列在左侧；列表下方的 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. 如果您没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且地理区域（geo zone）和订单状态必须存在；如果任一字段有误，则不会保存任何内容。

Nets Nexi（北欧国家）

Enable/Disable：Enable Nets Nexi Gateway 用于开启或关闭该支付方式。默认：关闭。

Title：结账时向顾客显示的支付方式名称。它也是订单中保存的支付方式名称。默认：Nets Easy。必填。

Description：顾客在 Confirm Order 步骤看到的文字。默认：Pay securely with Nets Easy。

Sort Order：Nets 在结账时支付方式中的排列位置。留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 Nets。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账总额（以商店默认币种计算），达到后才会提供 Nets。留空则对任何金额都提供 Nets。

API 密钥

从 Nets Easy 门户的 Company > Integration 中复制密钥：测试密钥来自测试门户（test.portal.dibspayment.eu），正式密钥来自正式门户（portal.dibspayment.eu）。本节提供了两个门户的链接。无需结账密钥。

Test Mode：测试模式使用 test.api.dibspayment.eu 和测试密钥；正式模式使用 api.dibspayment.eu 和正式密钥。订单的退款和扣款始终使用付款时所在的环境。默认：开启。开启时，顾客在 Confirm Order 步骤会看到 Test mode: no real money will be charged.

Test Secret Key：您的 Nets 测试环境密钥（secret API key）。

Live Secret Key：您的 Nets 正式环境密钥（secret API key）。

已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。

付款

Webhooks：Nets 通知（webhook）会随每笔付款自动注册。Nets 门户中无需任何配置。该字段显示通知的发送地址。OpenCart 3 中的地址形式类似 https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook，OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook，由您的 OpenCart 安装的商店地址生成。如果它不是公共 HTTPS 地址，该字段会警告您商店无法接收 webhook；此时，付款会在顾客返回商店时确认，或通过订单页面上的 Nets: check payment status and capture 确认。系统会注册以下事件：

每个 webhook 都必须包含扩展为该付款生成的随机密钥。没有正确密钥的 webhook 会被拒绝。webhook 只告诉扩展哪笔付款发生了变化：付款本身始终使用付款所在环境的密钥，从 Nets API 读取。

OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单，missing order）。只有在从 Nets API 读回付款（webhook、顾客返回或订单页面上的 Nets: check payment status and capture）并且匹配的预授权已扣款之后，订单才会获得状态。下面的每个状态字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：Nets 确认并扣款付款后订单的状态。默认：Processing。选择 Complete 可将已付款订单标记为已完成。

Nets Payment On Hold Status：金额或币种与订单不一致、扣款失败，或顾客在订单取消后付款。不会自动扣款，并会添加备注说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Status：在 Nets 门户中取消订单的预授权时设置。默认：Canceled。

Refunded Status：在订单页面全额退款后设置。默认：Refunded。

高级

Debug log：将 API 调用和付款状态变化记录到 OpenCart 日志文件夹（storage/logs）中的 nng_debug.log.php。该文件无法通过网页打开。密钥和顾客数据不会被记录。错误和警告始终会被记录，即使该选项关闭。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载扩展时会删除网关设置和日志。订单的 Nets 付款和退款记录始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥会保留。

结账

在 Payment Method 步骤，顾客选择支付方式（默认为 Nets Easy）。在 Confirm Order 步骤，顾客会看到您的描述以及 You will be redirected to the Nets payment page to pay securely. 的提示。OpenCart 在此步骤创建订单，此时仍没有状态。顾客点击 Confirm Order 后，扩展会以订单币种为订单总额创建 Nets 付款，并将商品、运费及其他订单总额（优惠券、礼品卡、手续费）作为订单明细一并提交，然后将顾客带到 Nets 托管的付款页面。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。Nets 中的付款参考号就是 OpenCart 订单号。顾客的电子邮件、姓名、收货地址和电话号码在 Nets 接受其格式时传递给 Nets。Nets 页面会链接到您商店的结账条款页面（如果未设置，则链接到商店首页）。

付款后，顾客返回您的商店。只有在 Nets 确认付款之后，订单才会被标记为已付款：扩展从 Nets API 读取付款信息，将预留的金额和币种与订单进行比对，对预授权进行扣款，然后才设置订单状态。这一过程通过 webhook 或顾客返回来完成，以先到者为准。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。如果付款尚无法确认（无法连接 Nets，或此时另一个请求正在确认），Payment confirmation 页面会显示 Your Nets payment is being confirmed. Your order will be updated 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. 在 OpenCart 4 中，这些提示显示在结账页面上方。购物车会保留。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则为结账保留同一个订单，并以新的 Nets 付款再次为该订单付款。重新尝试时，扩展会先检查该购物车之前的付款；如果其中一笔已付款，则确认该订单，而不会发起新的付款。否则，在开始新的 Nets 会话之前，会先关闭之前的会话。如果同一购物车的另一个订单已付款或处于暂挂状态，顾客会被带到成功页面。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在未付款的情况下被关闭（例如您取消了它，包括在 Nets 门户中取消预授权之后），顾客会被带回结账页面，并看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，从 Nets 返回时同样如此；下一次点击 Confirm Order 将为一个新订单付款。同一购物车中已付款随后被取消或退款的订单不再占用购物车。

如果 Nets 无法发起付款，顾客会停留在 Confirm Order 步骤并看到简短提示，例如 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. 详细信息会写入日志。

即使商店处于维护模式，webhook 仍然有效：OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展会为此添加一个启动操作（startup action），该操作也允许顾客从 Nets 返回。

该扩展只使用托管付款页面。它不提供页面内嵌的 Nets 结账、订阅或定期付款、已保存的银行卡、发票费用、仅授权模式，也不支持按发货进行部分扣款。

订单和退款

订单状态

No status（缺失订单，missing order）：顾客已被转到 Nets 但尚未付款，或付款尚未确认。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：Nets 已确认并扣款。备注会显示付款 ID、扣款 ID 和支付方式。

Nets Payment On Hold Status（默认 Pending）：Nets 中的金额或币种与订单不一致（未扣款），扣款被拒绝，或顾客在订单取消后付款（已预留，未扣款）。备注会说明原因。不会自动扣款。检查订单后，使用 Nets: check payment status and capture 进行扣款，或在 Nets 门户中取消预授权。

Cancelled Status（默认 Canceled）：订单的预授权已取消，例如在 Nets 门户中取消。

Refunded Status（默认 Refunded）：付款已通过扩展全额退款。

当 webhook 或顾客返回将订单从暂挂状态转为已付款状态，或将其取消时，OpenCart 会通知顾客。重复的 webhook 和页面刷新绝不会重复扣款或添加重复备注；已付款的订单也绝不会因 Nets 事件而再次被修改。如果针对已付款订单（或同一购物车的其他订单）完成了旧的付款链接，则第二笔预授权会自动释放；如果它已被扣款，备注会提示您在 Nets 门户中退款。如果订单是以其他方式被标记为已付款的，已预留的 Nets 付款不会被扣款，并会有备注说明这一点。

备注是订单 History 中的条目，顾客看不到。

VibeFox Nets Nexi Gateway 标签页

在 Sales > Orders 中打开一个通过 Nets 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox Nets Nexi Gateway 标签页会显示 Nets Easy payment 区块：付款 ID、扣款 ID、环境（测试付款会带有 Test environment 标签）、状态和支付方式、在 Nets 中预留和扣款的金额、订单总额和已退款金额、退款表单、退款历史以及订单的 Nets notes。该标签页显示给有权访问扩展的用户；其按钮需要修改扩展的权限（在 System > Users > User Groups 中设置）。

Nets: check payment status and capture：显示在尚未付款的订单上。它从 Nets 读取付款，并扣款与订单匹配的预授权，包括扣款失败之后，或您检查了暂挂订单之后。如果没有任何变化，备注会说明原因，例如顾客尚未完成付款。通过此按钮设置的状态，与通过退款设置的状态一样，会被直接修改，即作为手动状态变更，不发送邮件，也不产生库存变动。

退款

在该标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Nets。确认提示 Refund this amount through Nets? This cannot be undone. 付款被扣款后，支持全额和部分退款，退款金额上限为订单总额；仅预留的付款可在 Nets 门户中取消。退款会针对付款时所在环境中订单的扣款进行，因此必须已设置该环境的密钥。如果 Nets 不接受退款，标签页会显示错误，且不会记录任何退款。成功的退款会添加到退款历史和备注中，并附带 Nets 退款 ID。全额退款会将订单设置为 Refunded Status；部分退款不会改变状态。

Sales > Returns 中的商品退货不会通过 Nets 退还款项。在 Nets 门户中进行的退款不会同步；如有需要，请手动更新订单。

许可证密钥

该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Nets Nexi Gateway 是 Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店移除密钥）。其下方是 Product: opencart-payment-nets-nexi 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 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. 以同一浏览器登录后台的管理员用户，仍能在商店中看到该支付方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中该预览不可用：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该支付方式。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，退款也照常工作。

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Nets Nexi：请检查许可证是否有效、Enable/Disable 是否开启，以及所选模式是否有密钥：测试模式下为 Test Secret Key，正式模式下为 Live Secret Key。缺少密钥时，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍没有状态：webhook 没有到达您的商店。请检查商店是否使用 HTTPS，使 Webhooks 中的地址为公共 HTTPS 地址，并检查付款所在环境的密钥是否已设置。顾客付款后返回商店时，订单也会获得状态，或者可以在订单标签页中使用 Nets: check payment status and capture。

Webhook 返回 Unauthorized：webhook 没有携带该付款的密钥。只有带有付款时登记的密钥的 webhook 才会被接受。

Webhook 返回 Unknown payment：该付款不是由此商店创建的。

Webhook 返回 Busy, retry later、Payment lookup failed 或 Payment not reserved yet：另一个请求正在确认同一购物车，无法连接 Nets API，或预授权尚未可见。Nets 会自动重试 webhook。

Webhook 返回 Order could not be updated, retry later：无法设置订单状态。Nets 会重试 webhook。开启 Debug log 可查看原因。

Webhook 地址在浏览器中显示 Method not allowed：这是正常现象。该地址只接受来自 Nets 的请求。

顾客在 Confirm Order 之后看到错误：请开启 Debug log，并查看扩展页面中的 Log 字段。This payment method is temporarily unavailable. Please choose another payment method. 通常表示密钥错误或缺失。Nets 会在日志中报告被拒绝的币种。This payment method is not available. 表示结账会话已与订单不匹配，或支付方式在此期间已被关闭：顾客需要重新加载结账页面。

顾客看到 We could not match this payment to an order：返回链接不完整，或属于另一个订单。如果顾客已被扣款，请在 Nets 门户中查找该付款并检查订单。

付款后订单处于暂挂状态：请阅读标签页中的 Nets notes。如果扣款被拒绝，请使用 Nets: check payment status and capture 重试，或在 Nets 门户中扣款。如果金额或币种不一致，请在 Nets 门户中检查该付款。如果顾客在取消后付款，请检查订单，并扣款或取消预授权。

Refund via Nets 缺失或失败：只有在付款被扣款之后才能退款；此时标签页会显示扣款 ID。退款使用订单付款时所在环境的密钥，因此必须设置该密钥；否则标签页会指出缺少哪个环境的密钥。

对于开发人员：在创建付款之前，扩展会触发 OpenCart 事件 nng_create_payment_payload，并传入请求正文和订单；nng_currency_decimals 用于更改某个币种的小数位数。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Nets Nexi Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Payment 部分的订单状态，重新安装后这些设置会恢复为默认值。在 OpenCart 4 中，扩展的事件以及在维护模式下放行 webhook 的启动操作也会被删除。如果 Delete Data on Uninstall 已开启，则其他网关设置（标题、描述、测试模式、密钥、日志记录）和日志会被删除；如果关闭，则会保留，以便日后重新安装时使用。订单的 Nets 付款数据（付款、扣款和退款）始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Nets Nexi Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Nets、Nets Easy 和 Nexi 是其各自所有者的商标。本扩展与 Nets 或 Nexi 没有关联，也未获得其认可。