VibeFox Nexi XPay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

货币：购物车货币必须为 EUR。对于其他货币，结账时会隐藏该付款方式。

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

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Nexi XPay Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

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

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

安装时，模块会创建两个订单状态：Awaiting Nexi XPay payment 和 Nexi XPay payment on hold。PrestaShop 会为所有货币、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。模块安装后在店铺中启用的国家，也必须在那里勾选。

配置

所有设置都在模块页面：Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在测试模式开启时，页面字段上方会显示 Test mode is on: payments go to the Nexi XPay test environment, no real money is charged.。如果网关已启用，但当前模式的别名或 MAC 密钥为空，或者店铺的默认货币不是 EUR，页面会发出警告。在这些情况下，结账时会隐藏该付款方式。保存时会删除粘贴值前后的空格和换行。

Nexi XPay

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

标题：结账时显示给顾客的付款方式标题。它也是订单中保存的付款方式名称。默认：Credit Card (Nexi)。测试模式下，结账页面和订单会在标题后添加 (TEST MODE)。

描述：结账时显示给顾客的付款方式描述。默认：Pay securely with your credit card via Nexi XPay。

测试环境

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

Test Mode：使用 Nexi XPay 测试环境和测试凭据。关闭后，将使用正式凭据接受真实付款。默认：on。

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.。只有在需要更改时才输入新值。

清除已保存的密钥：勾选 Test MAC Key 或 Live MAC Key，然后点击 Save，即可删除已保存的密钥。空字段会保留已保存的值。

付款

Notification URL：仅供参考。每笔付款都会将其发送给 Nexi，因此无需在 Nexi 后台进行任何配置。使用友好 URL 时，它看起来像 https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}，可能包含 /it/ 之类的语言代码，并以购物车编号结尾。Nexi 会通过服务器对服务器的方式将付款结果发送至此 URL，并同时随顾客的返回一起传递。两者以相同方式签名，并使用付款所在环境的 MAC 密钥、该环境的别名以及为该购物车签发的交易代码进行验证。未通过验证的结果会被拒绝，且不会产生任何改动。

扣款：何时扣除款项。

付款后的订单状态：付款成功后订单的状态。

高级

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

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

Delete Data on Uninstall：开启时，卸载模块会删除所有模块设置和日志。订单中的 Nexi XPay 付款数据和订单状态会保留。默认：off。

结账

在付款步骤，顾客选择付款方式（默认为 Credit Card (Nexi)）并确认。下一页会显示 Redirecting to Nexi XPay for payment...，并自动将顾客带到 Nexi XPay 页面；同时提供 Pay Now 按钮作为备用。付款会以欧元发送购物车总额，附带新的交易代码、顾客的电子邮件、Cart 说明、购物车编号以及您的店铺名称。如果购物车语言为意大利语、英语、西班牙语、法语、德语、日语、中文、阿拉伯语、俄语或葡萄牙语，Nexi 页面将以该语言打开，否则以英语显示。此时尚不存在订单。

顾客付款后返回您的店铺。只有在收到与购物车金额和币种完全一致的、已验证的 Nexi 结果后，订单才会被标记为已付款：以先到达的服务器对服务器通知或签名的顾客返回页面为准。随后订单会被创建，顾客会看到标准的订单确认页面，并显示 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.。对于处于保留状态的订单（延迟扣款或人工审核），页面会显示 We have received your Nexi XPay payment authorization. Your order will be processed shortly.。如果待处理的付款之后失败，页面会显示 The payment was not completed. Please contact us.。

如果顾客返回时结果尚未处理，会显示一个页面，内容为 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.。不会创建订单，购物车会保留，因此顾客可以重新付款。如果购物车已经有订单（例如在另一个标签页中已付款），顾客会被带到订单确认页面，而不是进入新的付款流程。

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

即使店铺处于维护模式，通知仍然有效，且不受店铺国家限制的阻止。

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

订单和退款

订单状态

尚无订单：顾客已被转到 Nexi，但尚未付款、取消或被拒绝，或 Nexi 尚未确认付款。目前只存在购物车。

Payment accepted, Delivered or Nexi XPay payment on hold：Nexi 已确认付款。订单状态取决于 Order Status After Payment。付款会以 Nexi 交易代码作为交易 ID 记录，备注中会显示授权代码、交易代码、卡品牌以及 Nexi 消息。

Nexi XPay payment on hold（authorized）：已选择延迟扣款，付款仅获得授权。请在订单页面用 Capture Nexi XPay payment 进行扣款。

Awaiting Nexi XPay payment：Nexi 将付款报告为等待确认。订单将根据最终结果更新。

Nexi XPay payment on hold after payment：Nexi 返回的金额或币种与购物车不符（订单不会被标记为已付款），或者在订单已被取消后收到了成功的付款。备注会说明原因。请在 Nexi XPay 后台核对付款，并处理或退款该订单。

付款错误：待处理的付款失败。同一购物车无法再次付款，因此顾客必须重新下单。

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

Nexi XPay 付款区块

订单页面会显示 Nexi XPay payment 区块，其中包括交易代码（codTrans）、状态和 Nexi 结果、扣款方式、发送给 Nexi 的金额和收到的金额、授权代码、卡品牌、Nexi 消息和日期、测试付款的 Test environment 标记，以及订单的 Nexi XPay notes。

延迟扣款

对于处于保留状态的已授权订单，请点击区块中的 Capture Nexi XPay payment（按钮会显示金额），并确认提示 Capture the authorized amount through Nexi XPay?。您需要有编辑订单的权限。模块会在付款所在环境中，使用该环境的密钥扣除已授权金额，记录付款，并根据 Order Status After Payment 设置状态。如果扣款失败，区块会显示错误，并添加备注，订单保持在保留状态。同一笔付款的第二次扣款会被拒绝。

退款

退款不能从 PrestaShop 发起，因此 Nexi XPay 没有退款按钮。请在 Nexi XPay 后台办理退款，然后在 PrestaShop 中手动记录。订单页面上的 PrestaShop 标准退款按钮不会通过 Nexi 退还款项。

许可证密钥

本模块需要从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Nexi XPay Gateway 许可证区块位于 Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure 页面的顶部，在设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-payment-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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Nexi XPay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会得到确认，已授权的付款仍可扣款。

许可证到期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 Nexi XPay：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式是否具备两项凭据（测试模式下为 Test Alias 和 Test MAC Key，正式模式下为 Live Alias 和 Live MAC Key），以及购物车货币是否为 EUR。在这些情况下，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许 EUR、顾客所在国家和顾客所属客户组。

付款已完成，但未创建订单：通知和顾客返回都未被接受。请检查店铺能否从互联网访问，MAC 密钥和别名是否与付款所在环境（测试或正式）匹配，并开启 Debug Log，在模块页面的 Log 字段中查看 Nexi 发送的内容。

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

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

通知返回 not_configured 或 busy：付款所在环境的别名或 MAC 密钥为空，或者订单正被另一个请求同时更新，或者订单无法创建（例如模块已停用）。Nexi 会重试通知。

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

订单处于 Nexi XPay payment on hold after payment 状态：请阅读订单区块中的 Nexi XPay notes。原因可能是：选择了延迟扣款（请使用按钮扣款）、金额或币种不符、已取消订单又收到了付款，或已将 Nexi XPay payment on hold 设为付款后的状态。

Capture Nexi XPay payment 缺失或失败：该按钮仅对处于保留状态、以延迟扣款方式授权的 Nexi XPay 订单显示，并且仅对有权编辑订单的员工显示。如果付款所在环境的别名或 MAC 密钥为空，区块会提示。如果扣款失败，请阅读区块和备注中的错误信息，例如 Nexi XPay refused the capture 以及 Nexi 的代码和消息。

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

卸载

进入 Modules > Module Manager，打开 VibeFox Nexi XPay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单中的 Nexi XPay 付款数据以及订单状态 Awaiting Nexi XPay payment 和 Nexi XPay payment on hold 始终会保留，因此重新安装后仍可对已授权的付款进行扣款。现有订单会保留其付款备注和交易 ID。

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