VibeFox Niubiz for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
货币：秘鲁索尔（PEN）或美元（USD）。付款方式仅对使用这两种货币之一的购物车提供。对于其他货币，结账时会隐藏该付款方式。
Niubiz 账户：Niubiz 为每个环境签发一个商户号（código de comercio）、一个 API user 和一个 API password。沙盒凭据由 Niubiz 集成团队提供；正式环境凭据则在 Niubiz 认证您的集成之后提供。无需设置 webhook：Niubiz 会立即响应授权。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能在一个域名上使用。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Niubiz Payment 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 保持 Sandbox mode 开启，并输入沙盒的 merchant ID、API user 和 API password（参见配置）。
5. 开启 Enable/Disable，点击 Save，然后使用 Niubiz 测试卡进行几笔测试付款。
6. Niubiz 认证您的集成之后，输入正式环境凭据并关闭 Sandbox mode。
安装时，模块会创建订单状态 Niubiz payment on hold。PrestaShop 会将新的付款模块关联到所有货币、所有客户组以及当时处于启用状态的国家。您可以在 Payment > Preferences 中修改。请在那里确认模块已允许 PEN 或 USD。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Niubiz Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，如果店铺中没有启用 PEN 或 USD 货币，或者当前模式的凭据不完整，页面会向您发出警告（在这两种情况下，结账时都会隐藏该付款方式）。如果店铺的默认货币既不是 PEN 也不是 USD，页面会提示 Niubiz 仅对 PEN 或 USD 购物车提供。沙盒模式开启期间，页面会显示 沙盒模式已开启：付款将发送到 Niubiz 沙盒，不会产生任何真实扣款。
Niubiz
Enable/Disable: Enable Niubiz payments 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称。它也会作为付款方式名称保存在订单中。默认：Credit or debit card (Niubiz)。必填：空标题不会被保存，将保留之前的标题。
Description: 结账时显示在付款方式下方的文字。默认：Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.
Niubiz 凭据
Niubiz 会为沙盒提供一个 merchant ID、一个 API user 和一个 API password；认证之后，还会为正式环境提供这些凭据。开发者文档位于 desarrolladores.niubiz.com.pe。
Sandbox mode: 使用 Niubiz 沙盒（QA）环境，不会产生真实扣款。它会同时切换 API 端点和下方的凭据组。默认：开启。进行真实付款时请关闭。开启期间，顾客会在付款方式下方和付款页面上看到 沙盒模式：请使用 Niubiz 测试卡 — 不会产生任何真实扣款。
Sandbox merchant ID: 您沙盒账户的商户代码，仅限数字。空格会被去除。如果值包含其他字符，页面会显示错误并保留之前的值。其他字段仍会保存。
Sandbox API user: 沙盒的 API user。
Sandbox API password: 沙盒的 API password。
Production merchant ID: 您正式（已签约）账户的商户代码，仅限数字，并进行相同的检查。
Production API user: 正式环境的 API user。
Production API password: 正式环境的 API password。
已保存的密码不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 仅在需要更改时才输入新值。
Clear saved passwords: 勾选某个密码并点击 Save 即可将其删除。字段为空时将保留已保存的值。
付款表单
Logo URL: 可选的徽标 HTTPS 地址，显示在 Niubiz 付款表单中，尺寸约为 187 × 40 px。未设置时显示店铺名称。不是有效 https:// 地址的网址会被拒绝并显示错误，并保留之前的值。
高级
Debug log: 将 Niubiz API 调用记录到模块文件夹中的 logs/niubiz_p_debug.log.php。该文件无法通过网页打开。即使此开关关闭，错误和警告也会始终记录。凭据、令牌、银行卡和顾客数据永远不会被记录。默认：关闭。
Log: 显示日志的大小和最近的条目。点击 Clear log 可清空日志。
Delete data on uninstall: 开启时，卸载模块会删除其设置和日志。为订单保存的付款数据（Niubiz 尝试记录、订单备注）以及订单状态始终会保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Credit or debit card (Niubiz)）并提交订单。模块会向 Niubiz 请求访问令牌，并以购物车货币为购物车总额申请付款会话，然后打开您店铺的 Niubiz payment 付款页面。此时尚未创建任何订单。
在付款页面上，Niubiz 付款表单会自动打开。页面会显示 请在安全的 Niubiz 付款表单中完成付款 — 您的银行卡信息将在 Niubiz 中输入，而不是在本网站中。 页面还提供一个显示购物车总额的 Pay 按钮，用于重新打开表单，以及一个 Choose another payment method 链接。需要启用 JavaScript。如果 Niubiz 表单无法加载，页面会显示 无法加载 Niubiz 付款表单。请刷新页面或稍后再试。
顾客在 Niubiz 表单中输入银行卡信息。Niubiz 会向您的店铺返回一次性令牌，模块随后在服务器端以付款会话的金额、货币和购买编号进行授权，并且在创建该会话的环境中完成。付款会立即扣款。只有当 Niubiz 批准付款且响应与购物车一致时，订单才会被标记为已付款。之后订单会被创建，顾客会看到标准的订单确认页面。
银行卡被拒绝：不会创建订单。顾客会带着 Your payment was declined: 的提示和 Niubiz 的原因返回付款页面，可以用同一张卡或另一张卡重试。表单不会在提示信息上方重新打开；顾客需要点击 Pay。
Niubiz 无响应：如果 Niubiz 没有给出明确结果（超时、服务器错误、响应无法读取），订单会以 Niubiz payment on hold 状态创建，确认页面会显示 我们无法通过 Niubiz 确认您的付款。请勿重复付款 — 商店将核实付款并与您联系。 如果 Niubiz 批准了与购物车不一致的付款，页面会显示 您的付款已收到，正在由商店审核。如有其他需要，我们会与您联系。
请求被拒绝：如果 Niubiz 拒绝了请求本身（例如凭据无效或购买编号重复），不会创建订单，顾客会看到 Niubiz 无法处理付款，您的银行卡未被扣款。 原因会被写入日志。
购物车已变更：如果表单打开后购物车总额发生变化（例如在浏览器的另一个标签页中），付款将不会获得授权，顾客会看到 自付款表单打开以来您的购物车已发生变化，因此您的银行卡未被扣款。请核对总额后重新付款。
会话已过期：Niubiz 付款会话最长有效 20 分钟。如果会话已被使用、剩余时间不足 5 分钟、属于其他模式或其他商户号，或者购物车总额已变化，付款页面会创建新的会话。
每次付款尝试都会获得新的购买编号：购物车 ID 加上三位数的尝试编号（最多 12 个字符），因为 Niubiz 要求每次授权都使用唯一的购买编号。
模块仅接受一次性银行卡付款。不支持从 PrestaShop 退款或撤销，也不支持保存银行卡、订阅或定期付款，不提供分期（cuotas）选择，也不支持 PagoEfectivo、Yape 或其他电子钱包及二维码付款。因响应丢失而保留的订单不会被自动重新核对。
订单
订单状态
No order yet: 顾客位于付款页面且尚未付款，或银行卡被拒绝，或请求被拒绝。只存在购物车。拒绝和驳回的记录会写入模块日志。
Payment accepted: Niubiz 已批准付款，且响应与购物车一致。付款会以 Niubiz 交易 ID 记录，备注中会显示环境、交易 ID、授权码、购买编号以及带脱敏卡号的卡品牌。
Niubiz payment on hold, approved but not matching: Niubiz 批准了一笔付款，但其购买编号、金额或币种与购物车不一致，或其响应中不包含金额或币种。订单不会被标记为已付款。如果批准的币种与购物车货币相同，则批准金额会作为付款记录，并附带其交易 ID。备注会列出差异。请在 Niubiz 控制台中核对该交易。
Niubiz payment on hold, no definitive answer: Niubiz 没有明确响应，因此银行卡可能已被扣款。不会记录任何付款。备注中会给出购买编号。请在 Niubiz 控制台中查询：如果交易已批准且正确，请将订单设为 Payment accepted；否则请取消。
如果某个已有订单的购物车又收到了第二笔付款的响应，不会创建第二个订单。订单备注会给出购买编号、交易 ID 和金额，以便您在 Niubiz 控制台中核对，并在需要时退款或作废。
Niubiz 付款区块
订单页面会显示一个 Niubiz payment 区块，包含购买编号、环境（沙盒或正式）、交易 ID、授权码、银行卡信息以及订单备注。对于处于 Niubiz payment on hold 状态的订单，该区块会提醒您在 Niubiz 控制台中核对购买编号。该区块为只读。
退款
无法从 PrestaShop 进行退款和取消。请在 Niubiz 控制台中退款或作废该交易，然后手动更新订单。订单页面上的 PrestaShop 标准退款按钮不会通过 Niubiz 退还款项。
许可证密钥
模块需要使用一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Niubiz Payment 是 Modules > Module Manager > VibeFox Niubiz Payment > Configure 页面顶部的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除密钥）。其下方是一行 Product: presta-payment-niubiz 以及链接 Manage licenses and domains in your account，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 密钥未找到、该密钥属于其他产品、已达到域名数量上限，或 许可证已于某日期到期。店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。将密钥从店铺中移除并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
如果没有有效的密钥，结账时不会向顾客显示 Niubiz。如果仍然启动了付款，顾客会看到 此付款方式不可用。请选择其他方式。 PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已启动的付款仍会被确认。
许可证到期后，模块仍会继续工作，但更新和支持需要续期。在您于后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Niubiz：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 merchant ID、API user 和 API password 是否已填写（沙盒模式下为沙盒字段，否则为正式字段），以及购物车货币是否为 PEN 或 USD。如果凭据或货币有误，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否已允许购物车货币、顾客所在国家以及顾客所属的客户组。
付款已成功，但没有创建订单：Niubiz 不会为此付款表单提供 webhook，因此订单仅通过授权响应来创建。如果顾客没有完成表单，则不会有订单。否则，请查看模块页面中的 Log 字段，并在 Niubiz 控制台中查询购买编号。如果 Niubiz 已响应但订单无法创建（例如模块已被禁用），顾客会看到 您的付款已收到，但无法自动完成订单。请与我们联系 — 请勿重复付款。，并且当顾客再次打开付款页面时，模块会再次尝试创建订单。
顾客看到“无法连接到 Niubiz”：无法获取访问令牌。请检查当前模式的 API user 和 API password，并确认您的服务器可以访问 Niubiz API。开启 Debug log 以查看详细信息。
顾客看到“无法启动 Niubiz 付款”：Niubiz 没有创建付款会话。请检查当前模式的 merchant ID 和日志。
顾客看到“此付款尝试已处理”：同一表单被提交了两次。顾客需要在付款页面重新发起付款；银行卡不会被重复扣款。
顾客看到“此订单正在付款中”：另一个请求此刻正在对同一购物车进行授权。顾客应稍等片刻，并先查看电子邮件，然后再重试。
日志显示 Niubiz 报告了重复授权：Niubiz 已经记录了该购买编号。请在 Niubiz 控制台中核对；顾客可以使用新的购买编号重试。
订单处于 Niubiz payment on hold：请阅读 Niubiz payment 区块中的备注。Niubiz 没有给出明确结果，或批准了与购物车不一致的付款。请在 Niubiz 控制台中查询购买编号，然后将订单设为 Payment accepted 或取消。
保存设置时出错：merchant ID 只能包含数字，徽标 URL 必须是有效的 https:// 地址。将保留之前的值。
面向开发者：如果 Niubiz 要求发送特定于商户的反欺诈字段（MDD），其他模块可以通过钩子 actionNiubizPMerchantDefineData 添加这些字段。随付款会话发送的持卡人数据可以通过钩子 actionNiubizPCardholderData 修改。
卸载
进入 Modules > Module Manager，打开 VibeFox Niubiz Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块的设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Niubiz 付款尝试记录（购买编号、环境、交易 ID）和订单状态 Niubiz payment on hold 始终作为付款历史保留。现有订单会保留其付款备注和交易 ID。
Niubiz 是其各自所有者的商标。本模块与 Niubiz 无关联，也未获得 Niubiz 的认可。