VibeFox Nexi XPay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。

PHP：8.0 或更高版本。

货币：店铺或订单货币必须为 EUR。其他货币下，结账时会隐藏该付款方式。

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

公开网站：通知 URL 必须可从互联网访问，不能处于维护模式，也不能有阻止 Nexi 的基本身份验证或防火墙规则。否则，付款仍会通过顾客签名的返回信息确认。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_nexi_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Nexi XPay > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

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

6. 开启 Enable/Disable 并下一笔测试订单。一切正常后，输入正式别名和 MAC 密钥，并取消勾选 Test Mode。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > Nexi XPay。在字段上方，页面会在测试模式开启时显示 测试模式已开启：付款将发送到 Nexi XPay 测试环境，不会扣除真实款项。；如果网关已启用，但当前模式的别名或 MAC 密钥为空，或者店铺货币不是 EUR，页面也会发出警告。两种情况下，结账时都会隐藏该付款方式。保存时会自动删除粘贴密钥前后的空格和换行。

常规

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

Title：顾客在结账时看到的付款方式标题。默认：Credit Card (Nexi)。测试模式下，结账页面会在标题后添加 (TEST MODE)。

Description：顾客在结账时看到的付款方式描述。默认：Pay securely with your credit card via Nexi XPay.

测试环境

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

Test Mode：Enable test mode 使用 Nexi XPay 测试环境和测试凭据。取消勾选即可使用正式凭据接受真实付款。默认：开启。

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 计算密钥。

付款

每笔付款都会向 Nexi 发送通知 URL，因此无需在后台进行任何配置。该区域会显示此 URL，格式类似 https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}，末尾为订单 ID。Nexi 会通过服务器对服务器的方式将付款结果发送到此 URL，并同时通过顾客返回信息传递。两者的签名方式相同，并使用付款所在环境的 MAC 密钥、该环境的别名以及为该订单签发的交易代码进行核对。未通过核对的结果会被拒绝，且不会产生任何变化。

Capture：何时扣款。

Immediate capture：付款立即扣款，订单标记为已付款（默认）。

Deferred capture (authorize only)：扣款取决于您的终端配置。订单会以已授权状态被置为保留，直到您使用订单操作 Capture Nexi XPay payment 扣款，或在 Nexi 后台扣款后将订单状态改为处理中。

Order Status After Payment：付款成功后订单的状态。状态会立即设置，只发生一次状态变更并发送一封邮件。

处理中（WooCommerce 默认）：默认值。

已完成：每个已付款订单都会变为已完成。

保留：每个已付款订单都需要等待您的人工审核。

高级

Debug Log：Enable logging 会将付款事件记录到 WooCommerce > Status > Logs，来源为 wcp_nexi_gateway。日志不记录 MAC 密钥、银行卡数据或电子邮件地址。错误和警告（例如 MAC 校验失败）即使在该选项关闭时也始终会被记录。默认：关闭。

Delete Data on Uninstall：Remove all plugin settings and logs when uninstalled。默认：关闭。

结账

顾客选择付款方式（默认为 Credit Card (Nexi)）并下单。下一页会显示 正在跳转到 Nexi XPay 付款...，并自动将顾客带到 Nexi XPay 页面，同时提供 Pay Now 按钮作为备用。付款会以 EUR 发送，包含新的交易代码、顾客的电子邮件、说明 Order、订单号和您的站点名称。如果店铺语言为意大利语、英语、西班牙语、法语、德语、日语、中文、阿拉伯语、俄语或葡萄牙语，Nexi 页面将以该语言打开，否则以英语打开。

顾客完成付款后返回您店铺的订单接收页面。只有在收到经核实、金额和币种与订单完全一致的 Nexi 结果后，订单才会被标记为已付款：无论是服务器对服务器的通知，还是签名的顾客返回信息，以先到者为准。

如果付款被拒绝，或顾客在 Nexi 页面取消，他们会返回结账页面（购物车为空时则返回 Pay for order 页面），并看到以下消息之一：付款未完成。请重试或选择其他付款方式。、付款已取消。请重试。或 我们无法确认付款。如果您的银行卡已被扣款，请在再次付款前与我们联系。 在 Nexi 页面取消不会改变订单，因此顾客可以再次付款。

如果插件未针对当前模式完成设置，顾客会看到 该付款方式目前不可用。请选择其他付款方式。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

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

订单与退款

订单状态

待付款：顾客已被转到 Nexi，但尚未付款，或在 Nexi 页面取消。

处理中、已完成或保留：Nexi 已确认付款。状态遵循 Order Status After Payment 的设置。订单备注会显示授权代码、交易代码、银行卡品牌和 Nexi 消息。交易 ID 即 Nexi 交易代码。

保留（已授权）：已选择延迟扣款，付款仅完成授权。请使用订单操作 Capture Nexi XPay payment 进行扣款。

保留（待定）：Nexi 报告付款正在等待确认。订单将根据最终结果更新。

付款后保留：Nexi 返回的金额或币种与订单不符（订单不会标记为已付款），或者在订单已取消后收到了一笔成功付款。订单备注会说明原因。请在 Nexi XPay 后台核查该笔付款，并处理或退款该订单。

失败：最近一次付款尝试被拒绝、取消或因错误而结束。顾客可以再次付款。

已付款订单不会因后续失败而被降级。如果已付款订单又收到另一笔成功付款，备注会提示您如果属于重复付款，请在 Nexi XPay 后台退款。

延迟扣款

对于处于保留状态的已授权订单，打开订单，在订单操作中选择 Capture Nexi XPay payment，然后点击箭头。插件会在付款所在环境中扣除授权金额，并以 Order Status After Payment 中的状态将订单标记为已付款。如果扣款失败，错误会显示在订单页面并添加到订单备注中，订单保持保留状态。

退款

退款不通过 WooCommerce 进行，因此没有 Refund via 按钮。请在 Nexi XPay 后台完成退款，然后在 WooCommerce 中手动记录。

许可证密钥

插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Nexi XPay 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额，请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，Nexi XPay 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 该付款方式不可用。请选择其他付款方式。 已登录的店铺管理员仍能看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前配置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，延迟付款仍可扣款。

许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时未显示 Nexi XPay：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否同时具有两项凭据（测试模式为 Test Alias 和 Test MAC Key，正式模式为 Live Alias 和 Live MAC Key），以及店铺或订单货币是否为 EUR。在这些情况下，设置页面会显示警告。

付款已完成，但订单仍为待付款：通知和顾客返回信息均未被接受。请检查店铺是否可从互联网访问，MAC 密钥和别名是否与付款所在环境（测试或正式）匹配，并开启 Debug Log，在 WooCommerce > Status > Logs（来源 wcp_nexi_gateway）中查看 Nexi 发送的内容。

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

通知返回 unknown_transaction：该交易代码并非本店铺为该订单签发。结果将被忽略。

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

订单在付款后处于保留状态：请阅读订单备注。原因可能是选择了延迟扣款（请使用订单操作扣款）、金额或币种不匹配、订单已取消后收到付款、付款在 Nexi 处于待定状态，或者付款后状态选择了保留。

Capture Nexi XPay payment 缺失或失败：该操作仅在处于延迟扣款授权保留状态的 Nexi 订单中显示。如果失败，请阅读订单备注中的错误；扣款使用付款所在环境的密钥。

许可证区块显示错误：请按照区块中的提示操作。例如，如果密钥已在另一个域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后已知的状态继续运行。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete Data on Uninstall 时，网关设置和日志才会被删除；否则它们将保留，以便日后重新安装时使用。现有订单会保留其付款备注和交易 ID。

Nexi 和 XPay 是其各自所有者的商标。本插件与 Nexi 无关联，也未获得 Nexi 的认可。