VibeFox Niubiz for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：必须在 System > Localisation > Currencies 中启用秘鲁索尔（PEN）或美元（USD）。仅当顾客使用这些货币之一付款时，才会提供该付款方式。对于其他货币，结账时会隐藏该付款方式。

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

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

安装

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

OpenCart 3

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

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

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

4. 保持 Sandbox mode 开启，并输入沙盒的商户 ID、API 用户和 API 密码（参见 Configuration）。

5. 开启 Enable/Disable，点击 Save，然后使用 Niubiz 测试卡进行几笔测试付款。

6. Niubiz 认证您的集成之后，输入生产凭据并关闭 Sandbox mode。

OpenCart 4

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

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

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

4. 输入许可证密钥和 Niubiz 凭据，并按照 OpenCart 3 的步骤 3 至 6 测试付款。两个版本的设置页面及其字段相同。

新安装时，付款方式默认关闭，沙盒模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果商店中未启用 PEN 或 USD 货币，或者当前模式的凭据不完整，页面会向您发出警告（在这两种情况下，结账时都会隐藏付款方式）。如果商店的默认货币既不是 PEN 也不是 USD，页面会告知您：只有当顾客使用 PEN 或 USD 付款时才会提供 Niubiz。沙盒模式开启期间，页面会显示 Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. 如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，错误的值不会被保存：页面会在设置上方显示错误，该字段恢复为之前的值，其他字段则会正常保存。这适用于空的或超过 128 个字符的 Title、不是纯数字的商户 ID、不以 https:// 开头的 Logo URL、不是整数的 Sort Order，以及不是 0 或更大数字的 Total。

Niubiz

Enable/Disable：开启或关闭 Niubiz 付款。默认：off。

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Credit or debit card (Niubiz)。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中，显示在确认按钮上方、向顾客展示的文字。默认：Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Sort Order：结账时 Niubiz 在付款方式中的位置。可留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 Niubiz。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 上，如果商店不要求付款地址，则使用送货地址。

Total：订单必须达到的结账总额（以商店默认货币计）才会提供 Niubiz。留空则对任何金额都提供 Niubiz。

Niubiz 凭据

Niubiz 为沙盒（QA）提供商户 ID、API 用户和 API 密码，在认证后还会为生产环境提供。已经发起的付款始终使用其自身模式的凭据进行授权。

Sandbox mode：使用 Niubiz 沙盒，不产生真实扣款。它会同时切换 API 端点和下方的凭据集。默认：on。关闭后即可使用生产凭据接收真实付款。开启期间，顾客在 Confirm Order 步骤和付款页面会看到 SANDBOX MODE: use Niubiz test cards — no real charges are made.

Sandbox merchant ID：您沙盒账户的商户代码（código de comercio），仅限数字。空格会被去除。

Sandbox API user：沙盒的 API 用户，通常是一个电子邮件地址。

Sandbox API password：沙盒的 API 密码。

Production merchant ID：您生产（关联）账户的商户代码，仅限数字。

Production API user：生产环境的 API 用户。

Production API password：生产环境的 API 密码。

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

付款表单

Logo URL：可选项，您的 Logo 地址，显示在 Niubiz 付款表单中。必须是 https:// 地址。留空则显示商店名称。

订单

OpenCart 在 Confirm Order 步骤中创建订单，但不设置状态（即缺失订单）。只有在 Niubiz 响应授权之后，订单才会获得状态。下面每个字段都列出您 OpenCart 的订单状态。

Order Status After Payment：Niubiz 已批准付款，并且购买编号、金额和货币与订单一致。默认：Processing。

On Hold Status：Niubiz 批准了与订单不匹配的付款，或未给出明确答复，因此银行卡可能已被扣款。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

高级

Debug log：将 Niubiz API 请求和付款步骤写入 OpenCart 日志文件夹（storage/logs）中的 niubiz_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会移动到 niubiz_p_debug.old.log.php。即使此开关关闭，错误和警告也始终会记录。密码、令牌以及银行卡和顾客数据从不记录。默认：off。

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

Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。订单中的 Niubiz 付款信息（购买编号、交易 ID）始终会保留。默认：off。

导入 / 导出

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

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 密码会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit or debit card (Niubiz)）。在 Confirm Order 步骤中，顾客会看到您的说明以及提示 You will complete the payment in the secure Niubiz payment form. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 上，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会向 Niubiz 请求访问令牌，并以订单货币为订单总额创建付款会话，然后打开您商店的 Niubiz payment 页面。如果无法创建会话，顾客将停留在 Confirm Order 步骤，并看到简短提示，例如 We could not connect to Niubiz. Please try again in a few minutes.

在付款页面，Niubiz 付款表单会自动打开。页面显示 Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. 页面还有一个带订单总额的 Pay 按钮，用于再次打开表单，以及一个 Choose another payment method 链接，用于返回结账页面。需要启用 JavaScript。如果无法加载 Niubiz 表单，页面会显示 The Niubiz payment form could not be loaded. Please reload the page or try again later.

顾客在 Niubiz 表单中输入银行卡信息。Niubiz 会向您的商店返回一次性令牌，扩展随后使用会话的金额、货币和购买编号在服务器端进行授权，且与创建会话时所在的环境一致。付款会立即扣款。只有在 Niubiz 确认并且响应与订单一致之后，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。

银行卡被拒：订单保持无状态，并为其添加一条备注。顾客将带着 Your payment was declined: 以及 Niubiz 给出的原因返回付款页面，可以使用同一张卡或其他银行卡重试。表单不会在该提示上方重新打开；顾客需点击 Pay。

Niubiz 无响应：如果 Niubiz 没有给出明确答复（超时、服务器错误、无法解析的响应），订单会获得 On Hold Status，成功页面会显示 We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. 如果 Niubiz 批准了与订单不匹配的付款，成功页面会显示 Your payment was received and is being reviewed by the store. We will contact you if anything else is needed.

请求被拒绝：如果 Niubiz 拒绝请求本身（例如凭据无效或购买编号重复），订单保持无状态，并添加一条备注，顾客会看到 Niubiz could not process the payment and your card was not charged. 如果当时无法连接 Niubiz API，顾客会看到 We could not connect to Niubiz and your card was not charged. Please try again in a few minutes.

订单已更改：如果提交表单时订单总额与会话不再一致，则不会授权付款，顾客会看到 Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again.

会话过期：Niubiz 付款会话的有效期最长为 20 分钟。当会话已被使用、剩余时间不足 5 分钟、属于其他模式或商户 ID，或订单总额已更改时，付款页面会创建新的会话。

每次付款尝试都会获得新的购买编号：订单编号后加上三位数的尝试编号，因为 Niubiz 要求每次授权都使用唯一的购买编号。每次显示 Confirm Order 步骤时，OpenCart 3 都会创建一个新订单。OpenCart 4 则为结账保留一个订单并更新它，因此银行卡被拒后，顾客会以新的购买编号支付同一个订单。但已付款的购物车不会再次付款：顾客会被带到已付款订单的成功页面。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间已在未付款的情况下被关闭（例如您取消了它），顾客会被带回结账页面，并看到 Your previous order was cancelled or its payment failed. Please confirm the order again.，下一次点击 Confirm Order 将支付一个新订单。如果该订单已有状态，且购物车中现在有其他商品或数量，提示为 Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. 在 OpenCart 4 上，使顾客返回结账页面的提示（例如 The Niubiz payment could not be found. Please confirm your order again.）会显示在结账页面上方。

付款页面、Niubiz 表单的答复以及返回店铺的操作，在店铺处于维护模式时同样有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 上，扩展为这些请求添加了一个启动动作（startup action）。

该扩展仅接受一次性银行卡付款。它不支持从 OpenCart 发起退款或取消，不支持保存银行卡、订阅或定期付款，不支持分期付款（cuotas）选项，也不支持 PagoEfectivo、Yape 或其他钱包及二维码付款。因响应丢失而被挂起的订单不会被自动重新检查。

订单

订单状态

无状态（缺失订单）：顾客正在付款页面且尚未付款，或银行卡被拒绝，或请求被拒绝。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。拒绝和被拒绝的记录会添加到订单备注中。

在 OpenCart 4 上，结账中未付款的订单可能获得 Voided 状态（当顾客返回 Confirm Order 步骤时，OpenCart 4 会设置该状态）。扩展将此类订单视为无状态订单，之后的付款仍会确认该订单。

Order Status After Payment（默认 Processing）：Niubiz 已批准付款，且响应与订单一致。备注中会显示环境、交易 ID、授权码、购买编号，以及银行卡品牌和已遮盖的卡号。

On Hold Status（默认 Pending），已批准但不匹配：Niubiz 批准了一笔付款，其购买编号、金额或货币与订单不同，或其响应中不包含金额或货币。订单不会被标记为已付款。备注会列出差异。请在 Niubiz 控制台中检查该交易。

On Hold Status（默认 Pending），没有明确答复：Niubiz 没有给出明确答复，因此银行卡可能已被扣款。备注中会给出购买编号。请在 Niubiz 控制台中查询：如果交易已批准且正确，将订单设为已付款状态；否则取消该订单。

如果对于已付款的购物车又收到了第二笔付款的响应，不会设置第二个状态。已付款订单上的备注会给出购买编号、交易 ID 和金额，便于您在 Niubiz 控制台中核对，并在必要时退款或撤销。

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

VibeFox Niubiz Payment 选项卡

在 Sales > Orders 中打开一个通过 Niubiz 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox Niubiz Payment 选项卡会显示购买编号、环境（沙盒或生产）、Niubiz answer、交易 ID、授权码、银行卡、金额（以及 Niubiz 批准的金额）、发现的问题、尝试次数，以及该订单的 Niubiz notes。对于处于挂起状态的订单，该选项卡会提醒您在 Niubiz 控制台中核对购买编号。该选项卡为只读，仅向有权访问此扩展的用户显示。

退款

OpenCart 无法进行退款和取消。请在 Niubiz 控制台中对交易进行退款或撤销，并手动更新订单状态。在 Sales > Returns 中的商品退货不会通过 Niubiz 退还款项。

许可证密钥

该扩展需要一个在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Niubiz Payment 是 Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit 页面上位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店中移除密钥）。其下方有一行 Product: opencart-payment-niubiz，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。更改商店地址后，或在账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

结账时没有出现 Niubiz：请检查许可证是否有效，Enable/Disable 是否开启，当前模式的商户 ID、API 用户和 API 密码是否已填写（沙盒模式填写沙盒字段，否则填写生产字段），以及顾客是否使用 PEN 或 USD 付款。当凭据或货币有误时，设置页面会显示警告。另外，请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Niubiz 不为此付款表单提供 Webhook，因此订单只能从授权响应中获得状态。如果顾客没有完成表单，则未发生任何付款。否则，请查看扩展页面上的 Log 字段，并在 Niubiz 控制台中查询购买编号。如果 Niubiz 已响应但无法设置状态，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.，并且当顾客打开付款页面或再次确认购物车时，扩展会再次尝试设置状态。

顾客看到 We could not connect to Niubiz：无法获取访问令牌。请检查当前模式的 API 用户和 API 密码，以及您的服务器是否能够访问 Niubiz API。开启 Debug log 以查看详细信息。

顾客看到 We could not start the Niubiz payment：Niubiz 未能创建付款会话。请检查当前模式的商户 ID 和日志。

顾客看到 This payment attempt was already processed：同一表单被提交了两次。顾客需要在付款页面重新发起付款；银行卡不会被重复扣款。

顾客看到 This order is already being paid：另一个请求正在授权同一购物车。顾客应稍等片刻并查看邮件，然后再重试。

备注显示 Niubiz reported a duplicate authorization：Niubiz 已经掌握此购买编号。请在 Niubiz 控制台中核对；顾客可以使用新的购买编号重试。

订单处于挂起状态：请阅读 VibeFox Niubiz Payment 选项卡中的备注。Niubiz 没有给出明确答复，或批准了与订单不匹配的付款。请在 Niubiz 控制台中查询购买编号，然后将订单设为已付款状态或取消。

保存设置时出错：商户 ID 必须只包含数字，Logo URL 必须是有效的 https:// 地址，标题不能为空且不能超过 128 个字符。将保留之前的值。

面向开发者：如果 Niubiz 要求发送特定于商户的反欺诈字段（MDD），其他扩展可以通过 OpenCart 事件 niubiz_p_merchant_define_data 添加这些字段。随付款会话发送的持卡人数据可以通过事件 niubiz_p_cardholder_data 进行修改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Niubiz Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 上，还包括其事件和启动动作，该启动动作使付款页面、Niubiz 表单的答复以及维护模式下的返回得以通过）。如果开启了 Delete data on uninstall，其余网关设置（标题、说明、沙盒模式、凭据、Logo、日志选项）和日志都会被删除。如果关闭，则会保留，以便日后重新安装时使用。Niubiz 付款尝试记录（购买编号、环境、交易 ID）始终会作为付款历史保留。现有订单会保留其付款备注。

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

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