VibeFox Niubiz for WooCommerce — 帮助

系统要求

WordPress：5.8 或更高版本。

WooCommerce：6.0 或更高版本，已安装并启用。没有它插件无法启用。

PHP：8.0 或更高版本。

店铺货币：秘鲁索尔（PEN）或美元（USD）。其他货币下，结账时会隐藏该付款方式。

Niubiz 账户：Niubiz 为每个环境签发 merchant ID（código de comercio）、API user 和 API password。沙盒凭据由 Niubiz 集成团队提供，正式凭据则在 Niubiz 认证您的集成后提供。无需设置 Webhook：Niubiz 会立即响应授权。

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

安装

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

2. 点击 Activate。

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

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

5. 保持 Sandbox mode 开启，并输入沙盒的 merchant ID、API user 和 API password（参见配置）。

6. 开启 Enable/Disable，并使用 Niubiz 测试卡进行几笔测试付款。

7. Niubiz 认证您的集成后，输入正式凭据并取消勾选 Sandbox mode。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > 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：Use the Niubiz sandbox (QA) environment — no real charges。会同时切换 API 端点和下方的凭据组。默认：开启。取消勾选即可接受真实付款。

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。

付款表单

Logo URL：可选项，您的徽标在 Niubiz 付款表单中显示的 HTTPS 地址，约 187 × 40 像素。未设置时显示店铺名称。不以 https:// 开头的地址会被拒绝，并保留之前的值。

高级

Debug log：Log API calls 会将 Niubiz 请求写入 WooCommerce > Status > Logs，来源为 wcp_niubiz_payment。错误始终会被记录。凭据、令牌以及银行卡和顾客数据永远不会被记录。默认：关闭。

Delete data on uninstall：Remove the settings and logs of this plugin when it is deleted。停用插件从不会删除任何内容。订单中保存的付款数据会保留。默认：关闭。

1.0 版本只有一组凭据，其设置会自动迁移：如果测试模式开启，则迁移到沙盒字段，否则迁移到正式字段。

结账

顾客选择付款方式（默认为 Credit or debit card (Niubiz)）并下单。插件会向 Niubiz 请求订单总额对应的访问令牌和付款会话，然后将顾客带到您店铺的订单付款页面。沙盒模式下，结账页面和付款页面会显示 沙盒模式：请使用 Niubiz 测试卡，不会产生任何实际扣款。

付款页面会自动打开 Niubiz 付款表单。页面还提供一个显示订单总额的 Pay 按钮用于重新打开表单、一个 Cancel order 按钮，以及一个 Choose another payment method 链接。需要启用 JavaScript。如果无法加载 Niubiz 表单，页面会显示 无法加载 Niubiz 付款表单。请刷新页面或稍后重试。

顾客在 Niubiz 表单中输入银行卡信息。Niubiz 会向您的店铺返回一次性令牌，插件则使用订单自身的金额、币种和购买编号在服务器端完成授权。付款会立即扣款。只有当 Niubiz 批准付款且响应与订单一致时，订单才会被标记为已付款。随后顾客会看到订单接收页面。

银行卡被拒：顾客会返回付款页面，并显示 您的付款已被拒绝：以及 Niubiz 给出的原因，然后可以使用同一张卡或其他卡重试。表单不会在该消息上方重新打开；顾客需点击 Pay。

Niubiz 无响应：如果 Niubiz 未给出明确的结果（超时、服务器错误、无法读取的响应），顾客会看到订单接收页面，并显示 我们无法向 Niubiz 确认您的付款。请不要再次付款——商店将核实付款情况并与您联系。

会话过期：付款会话最长有效 20 分钟。当会话被使用或即将过期，或订单总额或模式发生变化时，付款页面会创建新会话。

每次付款尝试都会获得新的购买编号：订单 ID 后加三位数的尝试编号（最多 12 个字符），因为 Niubiz 要求每次授权都使用唯一的购买编号。顾客可以通过 Pay for order 页面重新支付未付款或失败的订单。

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

插件仅接受一次性银行卡付款。不支持 WooCommerce 退款或撤销，不支持保存银行卡、订阅或定期付款，不支持分期（cuotas）选择，也不支持 PagoEfectivo、Yape 或其他电子钱包及二维码付款。因响应丢失而处于保留状态的订单不会被自动重新核对。

订单

订单状态

待付款：顾客已被转到付款页面，但尚未付款。

处理中：Niubiz 已批准付款，且响应与订单一致。仅包含可下载虚拟商品的订单会变为已完成，与 WooCommerce 的常规做法一致。订单备注会显示环境、交易 ID、授权代码、购买编号，以及带脱敏卡号的卡品牌。订单的交易 ID 即 Niubiz 交易 ID。

失败：银行卡被拒绝。订单备注会显示 Niubiz 的原因、操作代码和购买编号。顾客可以再次付款。

保留，已批准但不匹配：Niubiz 批准了一笔付款，但其购买编号、金额或币种与订单不符，或其响应中不包含金额或币种。订单不会被标记为已付款；备注中会列出差异。请在 Niubiz 控制台中核查该交易。顾客会看到 您的付款已收到，正在由商店审核。

保留，没有明确结果：Niubiz 没有给出明确答复，因此银行卡可能已被扣款。备注中会提供购买编号。请在 Niubiz 控制台中查询：如果交易已批准且正确，请将订单设为处理中；如果不正确，请取消订单。

已取消：顾客在付款页面点击了 Cancel order，或订单被您取消，或因 WooCommerce 库存保留超时而取消。

如果 Niubiz 拒绝了请求本身（例如购买编号重复、HTTP 406 或凭据无效），订单状态不会改变。备注会说明银行卡未被扣款，顾客可以使用新的购买编号重试。

退款

无法通过 WooCommerce 进行退款或取消。请在 Niubiz 控制台中退款或撤销该交易，然后手动更新订单，例如在 WooCommerce 中执行手动退款。

许可证密钥

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

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

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

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

故障排除

结账时未显示 Niubiz：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 merchant ID、API user 和 API password 是否已填写（沙盒模式下为沙盒字段，否则为正式字段），以及货币是否为 PEN 或 USD。在 Pay for order 页面，以订单货币为准。如果凭据或货币有误，设置页面会显示警告。

付款已完成，但订单仍为待付款：Niubiz 没有针对该付款表单的 Webhook，因此订单只会通过授权响应更新。如果订单处于保留状态并带有备注，请在 Niubiz 控制台中查询购买编号。如果订单仍为待付款，说明顾客没有完成表单；请检查 WooCommerce > Status > Logs，来源 wcp_niubiz_payment。

顾客看到“无法连接到 Niubiz”：无法获取访问令牌。请检查当前模式的 API user 和 API password，并确认您的服务器能够访问 Niubiz API。开启 Debug log 以查看详细信息。

顾客看到“无法开始 Niubiz 付款”：Niubiz 未能创建付款会话。请检查当前模式的 merchant ID 和日志。

顾客看到“此付款尝试已处理”：同一表单被提交了两次。顾客需在付款页面重新发起付款；银行卡不会被重复扣款。

顾客看到“您的付款会话已过期，银行卡未被扣款”：付款页面打开的时间过长。顾客可以在同一页面重试。

订单备注：Niubiz 报告了重复授权：Niubiz 已记录此购买编号。请在 Niubiz 控制台中核查；顾客可以使用新的购买编号重试。

订单因 Niubiz 备注而处于保留状态：请阅读备注。Niubiz 没有给出明确结果，或批准了与订单不符的付款。请在 Niubiz 控制台中查询购买编号，然后将订单设为处理中或取消。

保存设置时出错：商户 ID 只能包含数字，徽标 URL 必须是有效的 https:// 地址。之前的值将被保留。

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

面向开发者：如果 Niubiz 要求您发送商户专属的反欺诈字段（MDD），请通过 niubiz_p_merchant_define_data 过滤器添加。键名为 MDD 加数字，值最长 100 个字符。其他过滤器：niubiz_p_cardholder_data（随付款会话发送的持卡人数据）、niubiz_p_purchase_number（单次尝试的购买编号，1 至 12 个字母或数字，每次尝试唯一）以及 niubiz_p_icon（付款方式的图标）。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete data on uninstall 时，网关设置和日志才会被删除。订单中保存的 Niubiz 数据（交易 ID、购买编号、脱敏银行卡）属于付款历史，始终保留。现有订单会保留其付款备注和交易 ID。

Niubiz 是其所有者的商标。本插件与 Niubiz 无关联，也未获得 Niubiz 的认可。