VibeFox Nexi XPay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

币种：顾客必须以 EUR 结账，因此必须在 System > Localisation > Currencies 中启用 EUR 币种。对于其他币种，支付方式会在结账时隐藏。

Nexi XPay 账户：您需要一个 Nexi XPay 商户账户（"Pagamento Semplice" 重定向集成），并持有终端的别名（alias，终端 ID）和 MAC 密钥。测试和正式凭据是分开的：测试凭据来自 Nexi XPay 测试区或开发者门户（developer.nexi.it），正式凭据则在商户账户激活后从您的 Nexi XPay 后台获取。无需在 Nexi 后台进行任何设置：返回地址和通知地址会随每笔付款一同发送。

公开的商店：通知 URL 必须能从互联网访问，不能有基本身份验证或阻止 Nexi 的防火墙规则。如果通知无法到达商店，付款仍会通过顾客签名的返回信息得到确认。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包括 README.txt、OpenCart 3 安装包 wcp_nexi_gateway-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_nexi_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 保持 Test Mode 开启，并输入测试别名和测试 MAC 密钥（参见配置）。

5. 开启 Enable/Disable，点击 Save，然后以 EUR 下一个测试订单。一切正常后，输入正式别名和正式 MAC 密钥，并关闭 Test Mode。

OpenCart 4

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

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

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

4. 与 OpenCart 3 的第 3 至第 5 步一样，输入许可证密钥、别名和 MAC 密钥。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见 Notification URL）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，测试模式开启时页面会显示 Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. 如果网关已启用，但当前模式的别名或 MAC 密钥为空，页面会发出警告（此时支付方式在结账时会被隐藏）；如果商店的默认币种不是 EUR，页面也会发出警告（此时支付方式仅向以 EUR 结账的顾客显示）。如果您没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不得超过 128 个字符，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且地理区域（geo zone）和订单状态必须存在；以上任一项有误，都不会保存任何内容。粘贴的别名和密钥前后的空格会被自动去除。

Nexi XPay

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

Title：结账时向顾客显示的支付方式名称。它也是订单中保存的支付方式名称。默认：Credit Card (Nexi)；标题留空则使用默认值。最多 128 个字符。在测试模式下，结账页面和订单会在标题后加上 (TEST MODE)；过长的标题会被缩短，以便带有 (TEST MODE) 的名称能放入订单的 128 个字符之内。

Description：顾客在 Confirm Order 步骤看到的文字。默认：Pay securely with your credit card via Nexi XPay。

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

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

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

测试环境

测试付款会发送到 int-ecommerce.nexi.it，绝不会对真实银行卡扣款。请在 Nexi XPay 测试区或开发者门户（developer.nexi.it，本节中有链接）获取测试别名和测试 MAC 密钥。

Test Mode：使用 Nexi XPay 测试环境和测试凭据。关闭后，将使用正式凭据接受真实付款。默认：开启。开启期间，顾客在 Confirm Order 步骤会看到 TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged.

Test Alias：您的 Nexi XPay 测试终端的别名（终端 ID）。

Test MAC Key：您的 Nexi XPay 测试终端的 MAC 计算密钥。

正式环境

商户账户激活后，正式别名和正式 MAC 密钥会显示在您的 Nexi XPay 后台（ecommerce.nexi.it）中。

Live Alias：您的 Nexi XPay 正式终端的别名（终端 ID）。

Live MAC Key：您的 Nexi XPay 正式终端的 MAC 计算密钥。

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

付款

Notification URL：仅供参考显示。其形式类似：OpenCart 3 为 https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}，OpenCart 4 为 https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}，末尾为订单号，由您的 OpenCart 安装的商店地址生成。它会随每笔付款发送给 Nexi，因此无需在 Nexi 后台进行任何配置。Nexi 会以服务器到服务器的方式将付款结果发送到此 URL，同时也会随顾客的返回一并传递。两者的签名方式相同，并会使用付款所在环境的 MAC 密钥、该环境的别名以及为该订单签发的交易代码进行校验。未通过校验的结果会被拒绝，且不会更改任何内容。

Capture：何时扣款。

Order Status After Payment：付款成功后订单的状态。每个选项所使用的 OpenCart 状态在 Orders 部分中设置。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单，missing order）。只有来自经验证的 Nexi 结果，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。OpenCart 没有 On hold 状态：默认使用 Pending，并由订单备注说明原因。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Status: Processing：当 Order Status After Payment 为 Processing 时使用。默认：Processing。

Status: Completed：当 Order Status After Payment 为 Completed 时使用。默认：Complete。

Status: awaiting payment：Nexi 将付款报告为待处理（esito PEN）。默认：Pending。

Status: on hold：金额或币种不一致、为已取消订单收到的付款、延迟扣款（已授权，尚未扣款），或 Order Status After Payment 被设置为 On hold。默认：Pending。

Status: payment failed：待处理的付款随后失败。默认：Failed。

Status of cancelled orders：您的商店用于已取消订单的状态。为此类订单收到的付款会被挂起，绝不会标记为已付款。扩展只读取此状态，从不设置它。默认：Canceled。

高级

Debug Log：将付款事件记录到 OpenCart 日志文件夹（storage/logs）中的 nexi_ip_debug.log.php。该文件无法通过网页打开。MAC 密钥、MAC 值、银行卡数据和电子邮件地址不会被记录。错误和警告（例如 MAC 校验失败）即使在该选项关闭时也始终会被记录。默认：关闭。

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

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

导入 / 导出

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

Import：粘贴导出的 JSON，然后点击 Import 以恢复设置。已保存的 MAC 密钥不会改变。

结账

在 Payment Method 步骤，顾客选择支付方式（默认为 Credit Card (Nexi)）。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择该方式，然后点击页面底部的 Confirm Order。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。顾客点击 Confirm Order 后，页面会显示 Redirecting to the Nexi XPay payment page... 和 Please do not close this window.，并在一秒后自动将顾客带到 Nexi XPay 页面；另外还提供一个 Pay with Nexi XPay 按钮作为备用。付款以 EUR 发送，金额为订单总额，附带一个新的交易代码、顾客的电子邮件，以及描述 Order、订单号和您的商店名称。如果顾客的商店语言是意大利语、英语、西班牙语、法语、德语、日语、中文、阿拉伯语、俄语或葡萄牙语，Nexi 页面会以该语言打开；否则以英语打开。

顾客完成付款后返回您的商店。只有在收到经过验证的 Nexi 结果，且金额和币种与订单完全一致之后，订单才会被标记为已付款：以先到者为准，可以是服务器到服务器的通知，也可以是签名的顾客返回。之后，订单会以 OpenCart 的标准方式获得状态，发送常规的订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 Your Nexi XPay payment has been received. 如果 Nexi 将付款报告为待处理，页面会显示 Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. 对于处于暂挂状态的订单（延迟扣款或人工审核），页面会显示 Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

如果顾客返回时结果尚未处理，Payment confirmation 页面会显示 We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. 并带有 Check again 按钮。通知一到达，就会设置订单状态。

如果付款被拒绝、待处理的付款失败，或顾客在 Nexi 页面取消，他会返回结账页面，并看到以下消息之一：The payment was not completed. Please try again or choose a different payment method.、Payment was cancelled. Please try again. 或 We could not confirm the payment. If your card was charged, please contact us before paying again. 在 OpenCart 4 中这些消息显示在结账页面上方。没有状态的订单会保持没有状态，购物车会保留，因此顾客可以再次付款。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则为结账保留一个订单，并以新的交易代码为同一订单重新付款；如果同一购物车的另一个订单已付款、待付款或处于暂挂状态，顾客会被带到成功页面，而不是进入新的付款。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即被关闭（例如待处理的付款失败，或您取消了它），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，从 Nexi 返回时同样如此；下一次 Confirm Order 会为新订单付款。如果订单已付款，之后被商店关闭（例如已退款），消息为 Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. 如果结账订单已经下达，之后购物车又发生了变化，消息为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 购物车的任何变化（包括数量变化）都视为需要单独付款的新购物车。

如果扩展未针对当前模式进行设置，顾客会看到 This payment method is not available right now. Please choose another payment method.

即使商店处于维护模式，通知仍然有效：OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展会为此添加一个启动动作，该动作同样会放行顾客从 Nexi 的返回。

该扩展只在 Nexi XPay 页面上接受付款。它不支持从 OpenCart 退款、保存的银行卡或 OneClick、订阅或定期付款、Pay-By-Link、XPay Build 嵌入式字段，也不支持在 OpenCart 中选择支付方式：Nexi 页面会显示您的终端上已启用的支付方式。

订单和退款

订单状态

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

Status: Processing, Completed or on hold：Nexi 已确认付款。状态跟随 Order Status After Payment。备注会显示授权码、交易代码、银行卡品牌和 Nexi 消息。

Status: on hold (authorized)：选择了延迟扣款，付款仅已授权。请在订单标签页中使用 Capture Nexi XPay payment 进行扣款。

Status: awaiting payment：Nexi 将付款报告为待确认。订单将根据最终结果更新。

Status: on hold after payment：从 Nexi 收到的金额或币种与订单不一致（订单不会被标记为已付款），或者在订单已取消后收到了成功的付款。备注会说明此情况。请在 Nexi XPay 后台检查该付款，并处理或退款该订单。

Status: payment failed：待处理的付款失败。

已付款的订单永远不会因为之后的失败而被降级。如果对已付款的订单，或对同一购物车的其他订单，又收到了一笔成功的付款，已付款订单上的备注会提示您，如果这是重复付款，请在 Nexi XPay 后台退款；第二个订单不会被标记为已付款。当待处理的付款之后成功或失败时，OpenCart 会将新状态通知顾客。

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

VibeFox Nexi XPay Gateway 标签页

在 Sales > Orders 中打开一个通过 Nexi XPay 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox Nexi XPay Gateway 标签页会显示交易代码（codTrans），测试付款会带有 Test environment 标签；此外还显示状态和 Nexi 结果、扣款模式和状态、发送给 Nexi 的金额和收到的金额、授权码、银行卡品牌、Nexi 消息、日期，以及订单的 Nexi XPay notes。该标签页显示给有权访问扩展的用户。

延迟扣款

对于处于暂挂状态、已授权的订单，请在标签页中点击 Capture Nexi XPay payment（按钮上显示金额），并确认提示 Capture the authorized amount through Nexi XPay? 您需要修改扩展的权限（在 System > Users > User Groups 中设置）。扩展会在付款所在的环境中，使用该环境的密钥扣款所授权的金额，并根据 Order Status After Payment 设置状态，同时添加备注。状态会像手动修改状态一样直接更改，不会发送邮件，也不会产生库存变动。如果扣款失败，标签页会显示错误，添加备注，订单保持暂挂。对同一笔付款的第二次扣款会被拒绝。

退款

OpenCart 不会执行退款，因此 Nexi XPay 没有退款按钮。请在 Nexi XPay 后台完成退款，然后在 OpenCart 中手动记录。Sales > Returns 中的商品退货不会通过 Nexi 退还款项。

许可证密钥

该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Nexi XPay Gateway 是 Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店移除密钥）。其下方是 Product: opencart-payment-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 账户中释放该名额。

没有有效的密钥时，结账页面不会向顾客显示 Nexi XPay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户，仍能在商店中看到该支付方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该支付方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，已授权的付款仍可扣款。

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

故障排除

结账时不显示 Nexi XPay：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否同时具备两项凭据（测试模式下为 Test Alias 和 Test MAC Key，正式模式下为 Live Alias 和 Live MAC Key），以及顾客是否以 EUR 结账。在上述情况下，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍没有状态：通知和顾客返回都未被接受。请检查商店是否可以从互联网访问，MAC 密钥和别名是否与付款所在的环境（测试或正式）相符；并开启 Debug Log，在扩展页面的 Log 字段中查看 Nexi 发送了什么。

通知返回 invalid_mac 或 invalid_alias：设置中的 MAC 密钥或别名与发送结果的终端不匹配。请从 Nexi 测试区或后台重新复制。

通知返回 unknown_transaction 或 order_not_found：该交易代码不是由此商店为该订单签发的，或该订单不存在。该结果会被忽略。

通知返回 not_configured 或 busy：付款所在环境的别名或 MAC 密钥为空，或者订单在同一时刻正被另一个请求更新。Nexi 会重试通知。

通知 URL 在浏览器中显示 method_not_allowed：这是正常现象。该 URL 只接受来自 Nexi 的请求。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不匹配，或支付方式在此期间已被关闭。顾客需要重新加载结账页面。

付款后订单处于暂挂状态：请阅读订单标签页中的 Nexi XPay notes。延迟扣款已选中（请使用按钮扣款），金额或币种不一致，为已取消订单收到了付款，或 Order Status After Payment 设置为 On hold。

Capture Nexi XPay payment 缺失或失败：该按钮只会在处于暂挂状态、已以延迟扣款方式授权的 Nexi XPay 订单上显示，并且只对有权修改扩展的用户显示。如果付款所在环境的别名或 MAC 密钥为空，标签页会说明这一点。如果扣款失败，请阅读标签页和备注中的错误信息，例如带有 Nexi 代码和消息的 Nexi XPay refused the capture。

测试付款不会确认正式付款：每笔付款都使用其发起时所在环境的密钥进行校验。请将 Test Mode 切换到您想要的模式，并使用该模式的别名和 MAC 密钥。

卸载

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

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

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