VibeFox Vindi for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：必须在 System > Localisation > Currencies 中设置巴西雷亚尔（BRL）。Vindi 仅以 BRL 收费，因此只有当顾客使用 BRL 付款时才会显示该付款方式。

Vindi 账户：您需要 Vindi 账户的 API 密钥。Vindi 沙盒是一个独立的 Vindi 测试账户，拥有自己的密钥。如果您希望提供 boleto、PIX 和 BolePix，还必须在您的 Vindi 账户中启用这些方式。

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

安装

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

OpenCart 3

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

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

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

4. 粘贴 Sandbox API key，准备就绪后再粘贴 Live API key。选择 Offered methods。

5. 将设置中的 Webhook URL 复制到 Vindi 中（参见配置）。

6. 开启 Enable / Disable 并点击 Save。在沙盒模式下进行测试付款，然后关闭 Sandbox mode 以接受真实付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、API 密钥、付款方式和 webhook。两个版本的设置页面及其字段相同。只有 Webhook URL 不同（参见付款通知（Webhook））。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Vindi Gateway > Edit。各部分列于左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示当前模式（TEST MODE 或 LIVE），并在当前模式的 API 密钥为空时发出警告（此时付款方式不会在结账时显示），或在店铺货币不是 BRL 时发出警告（此时仅当顾客使用 BRL 付款时才会显示付款方式）。若没有修改扩展的权限，页面会显示设置但无法保存。

保存时，密钥会按输入的原样保存，去除首尾空格。若未选择任何付款方式，则会保存信用卡，并且页面会显示 Choose at least one payment method — credit card was selected. 空的 Title 或超过 128 个字符的标题、不是整数的 Sort Order（允许负值）、不是大于或等于 0 的数字的 Total，或不存在的地理区域或订单状态，都不会被接受：不会保存任何内容，页面会显示相应提示，例如 Enter a title for the payment method (1 to 128 characters).

Vindi

Enable / Disable：Enable Vindi payments 开启或关闭该付款方式。默认：关闭。

Title：结账时显示的付款方式名称，也是订单中保存的付款方式名称。默认：Vindi。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中付款字段上方看到的文字。默认：Pay by credit card on the secure Vindi page, or by boleto / PIX。

Sort Order：Vindi 在结账付款方式中的位置。可留空或输入整数（允许负值）。

Geo Zone：仅向付款地址位于所选地理区域内的顾客提供 Vindi。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单需要达到的结账金额（以店铺默认货币计）才会提供 Vindi。留空则对任何金额都提供 Vindi。

API 密钥

在 Vindi 控制面板的 Settings > API keys 中创建密钥：正式环境使用 app.vindi.com.br，沙盒环境使用 sandbox-app.vindi.com.br。正式环境与沙盒环境使用独立的主机和密钥。每笔付款都会记录其账单创建的环境，因此检查、取消和退款始终使用该环境。

Sandbox mode：在 Vindi 沙盒中创建新付款，使用 sandbox-app.vindi.com.br 和沙盒 API 密钥。顾客在结账时会看到 TEST MODE 提示：Vindi sandbox: no real charges. 默认：开启。关闭它即可接受真实付款。

Live API key：正式 Vindi 账户的私钥。仅发送至 Vindi API。

Sandbox API key：Vindi 沙盒账户的私钥。

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

付款方式

Offered methods：顾客可以选择的付款方式。默认：信用卡。这些方式也必须在您的 Vindi 账户中启用。

Boleto、PIX 和 BolePix 需要顾客的 CPF 或 CNPJ，结账时会要求填写。

付款通知（Webhook）

Webhook 会告知您的店铺某个账单已付款、已取消、已被拒绝或已退款。本部分的 Webhook URL 字段会显示该 URL。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_vindi_gateway/webhook&token=...；在 OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_vindi_gateway/payment/wcp_vindi_gateway.webhook&token=...。它由您 OpenCart 安装的店铺地址生成，并包含扩展创建的一个密钥令牌。请按设置中显示的内容完整复制。在 Vindi 中，分别在正式账户和沙盒账户里进入 Settings > Webhooks，添加此 URL，并选择以下事件：

Vindi 不对其通知进行签名，因此缺少或令牌错误的请求会被拒绝；每条通知只会让扩展在订单变更前通过 Vindi API 重新读取账单。即使店铺处于维护模式，该 URL 也能正常工作（在 OpenCart 4 中，扩展的一个启动动作会放行 webhook 和付款状态页面）。Vindi 账单没有返回 URL，因此如果没有 webhook，银行卡付款只有在顾客使用同一购物车再次确认订单时才会被识别（届时会找到已付款的账单），而 boleto 或 PIX 付款则要等顾客在账户中再次打开订单时才会被识别（My Account > Order History）。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Vindi 报告账单后，订单才会获得状态；账单始终会从 Vindi 重新读取。boleto、PIX 和 BolePix 订单会在账单开具后立即获得等待状态。下方每个字段都列出您的 OpenCart 订单状态。OpenCart 没有暂挂状态，因此等待状态和暂挂状态默认都使用待处理；订单备注可以区分两者。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此选择。

Order Status After Payment：在 Vindi 付款得到验证后设置。默认：处理中。

Awaiting Vindi Payment Status：结账时已开具 boleto、PIX 或 BolePix；Vindi 稍后确认款项。付款数据会添加到顾客可见的历史备注中。默认：待处理。

Vindi Payment On Hold Status：账单正在 Vindi 审核中，已付账单与订单不匹配（货币、金额、账单代码或 Vindi 顾客），或订单已取消后才付款。备注会说明原因。默认：待处理。

Payment Error Status：Vindi 拒绝了等待中订单的付款尝试。顾客仍可支付同一账单；之后的付款会将状态设为付款后状态。默认：失败。

Canceled Status：等待中订单的账单已在 Vindi 中取消。当您将本扩展的订单设为此状态时，其待付款的 Vindi 账单也会被取消。默认：已取消。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将 API 调用和通知记录到 OpenCart 日志文件夹（storage/logs，在 OpenCart 4 中为 system/storage/logs）中的 wc_vdi_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。密钥、Webhook 令牌和顾客数据绝不会被记录。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除设置、Webhook 令牌、商品缓存和日志。订单以及订单的 Vindi 账单引用会保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Vindi）。在 Confirm Order 步骤中，顾客会看到您的描述。当提供多种方式时，付款框会显示 Pay with 以及信用卡、boleto、PIX 或 BolePix 的选项。当提供 boleto、PIX 或 BolePix 时，付款框还会有一个 CPF or CNPJ 字段。若未提供信用卡，则该字段为必填；否则会显示 Required for boleto and PIX. 如果顾客的自定义字段或名为 CPF 或 CNPJ 的地址中包含有效号码，该字段会自动填入。号码会通过校验位进行检查。若缺少内容，顾客会看到 Please choose how you want to pay with Vindi.、Please enter a valid CPF or CNPJ. 或 Please enter your CPF or CNPJ — it is required for boleto and PIX. 之一。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式；带有这些字段的付款框以及 Confirm Order 按钮位于结账页面底部。

当顾客点击 Confirm Order 时，扩展会根据付款地址为此购物车创建一个 Vindi 顾客，并为订单总额创建一个 Vindi 账单，采用单期付款。在 Vindi 中，该账单名称为 Order # 加上 OpenCart 订单号。

信用卡：顾客会被转到 Vindi 账单页面并在该页面付款。订单保持无状态。Vindi 的账单没有返回 URL，因此顾客不会自动返回店铺。当 Vindi 通过 webhook 确认付款后，订单才会获得状态。如果顾客使用同一购物车再次确认订单，且账单已付款，则已付款的订单会被确认，顾客会看到成功页面。

Boleto、PIX 和 BolePix：账单会立即开具，订单获得等待状态，顾客会进入 OpenCart 订单成功页面。在该页面以及顾客账户的订单详情中，Payment 部分会显示 PIX 二维码、带有 Copy code 按钮的 PIX 复制粘贴代码及其到期日期，以及一个 Open boleto 按钮。订单电子邮件和顾客的订单历史包含 PIX 代码和 boleto 链接。如果 Vindi 未返回 boleto 或 PIX 数据，则账单会被取消，顾客会看到错误信息。

只有在 Vindi 确认后，订单才会被标记为已付款：扩展会从 Vindi API 读取账单，并检查货币、账单是否属于该订单（账单代码和 Vindi 顾客），以及已付金额是否等于订单总额。成功页面和顾客账户中的订单页面会通过 API 对等待中的订单进行重新检查，最多每 15 秒一次。付款收到后，成功页面会显示 Your payment with Vindi has been received. 在付款尚未确认时，它会显示 We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. 对于已取消的订单，它会显示 This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

在付款尚未确认期间，成功页面以及顾客账户中的订单页面（针对等待中或暂挂的订单）还会显示一个 Check payment status 按钮。它会检查订单最新的 Vindi 账单。已确认或等待中的订单会带着付款数据回到成功页面。如果账单仍未付款，Payment 部分会显示 Your payment has not been completed yet. If you have already paid, the order is confirmed as soon as Vindi reports the payment — please do not pay again.，并提供 Pay at Vindi、Check again 和 Back to checkout 按钮。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，而 OpenCart 4 会更新结账中的订单，因此扩展只会对每个购物车付款一次。如果同一购物车的另一个订单已付款、正在等待 boleto 或 PIX，或处于暂挂状态，顾客会进入成功页面，且不会开具新账单。对同一订单的新付款尝试，如果付款方式、金额和环境都相同，则会复用其待付款的 Vindi 账单。否则，在创建新账单之前，会先在 Vindi 中取消之前的账单，这样顾客就无法对同一购物车付两次款。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面为止。银行卡付款被拒绝或账单被取消后，顾客会再次支付同一订单。如果此时该订单已在未付款的情况下被关闭，顾客会被送回结账页面，下一次点击 Confirm Order 将为新订单付款：已取消的订单会显示 This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.，付款失败的订单则显示 Your Vindi payment attempt was rejected. You can try again below. 在 OpenCart 4 中，将顾客带回结账页面的 Payment 状态页面消息会显示在结账页面上方。

如果 Vindi 无法开始付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如请检查 CPF / CNPJ、账单地址（boleto 需要街道、邮编、城市和州）、电子邮件或电话号码，或告知 Vindi 暂时不可用。技术原因会写入日志。

该扩展接受单期的一次性付款。它不支持订阅或定期扣款、已保存的银行卡、分期付款，也不在您的网站上提供银行卡表单：银行卡始终在 Vindi 页面中输入。门牌号和街区不属于 OpenCart 地址的一部分，因此不会发送给 Vindi。

订单与退款

订单状态

无状态（缺失订单）：银行卡付款已开始，但 Vindi 尚未确认。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示此类订单。在 OpenCart 4.1 中，此类订单也可能带有 Voided 状态，OpenCart 在再次显示确认步骤时会设置该状态；扩展会将其视为无状态订单。

Awaiting Vindi Payment Status（默认待处理）：boleto、PIX 或 BolePix 付款正在等待。当 Vindi 报告账单已付款时，订单会转为 Order Status After Payment。

Order Status After Payment（默认处理中）：付款已确认。订单会按照 OpenCart 的常规方式获得状态，发送常规订单邮件并更新库存。备注会显示 Vindi 账单、金额和环境。

Vindi Payment On Hold Status（默认待处理）：Vindi 账单正在审核，已付账单与订单不匹配（货币、金额、账单代码或 Vindi 顾客），或账单是在订单取消后才付款的。备注会说明情况。请检查订单和库存，然后完成订单或退款。

Payment Error Status（默认失败）：Vindi 拒绝了等待中订单的付款尝试。如有原因，备注会显示收单机构给出的原因。顾客仍可支付同一账单，之后的付款会将订单转为 Order Status After Payment。

Canceled Status（默认已取消）：等待中订单的账单已在 Vindi 中取消。当您在 OpenCart 中将订单设为此状态时，其待付款的 Vindi 账单也会被取消，因此无法再付款。如果无法取消，备注会要求您在 Vindi 控制面板中取消该账单。

Refunded Status（默认已退款）：付款已通过扩展全额退款。

如果某个已付款订单，或某个已付款购物车中的另一订单，又收到了第二笔账单的付款，订单不会被更改。已付款订单上的备注会要求您在 Vindi 中退还一笔付款。备注是订单历史记录（History）中顾客看不到的条目。

VibeFox Vindi Gateway 选项卡

在 Sales > Orders 中打开一笔通过 Vindi 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Vindi Gateway 选项卡会显示 Vindi bill、Charge、环境（沙盒付款会带有 Sandbox 标记）、Payment method、Status、Paid / refunded 金额、退款表单、退款历史、Bills of this cart（全部）以及订单的 Vindi notes。该选项卡仅向有权访问该扩展的用户显示。

退款

在 VibeFox Vindi Gateway 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Vindi。确认提示 Refund this amount through Vindi? This cannot be undone. 支持银行卡和 PIX 付款的全额和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款金额限制为 Vindi 实际收取的金额，因此金额出现差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款所在的环境（正式或沙盒）中发送，因此必须设置该环境的 API 密钥。

全额退款还会在 Vindi 中取消账单，并将订单设为 Refunded Status，但不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会改变状态。成功的退款会连同 Vindi 扣款和状态一起添加到退款历史和备注中。如果 Vindi 或收单机构拒绝退款，选项卡会显示错误，且不会记录任何退款。Vindi 报告账单已付款后，即可进行退款。

Vindi 无法退还 boleto 付款。选项卡会显示 Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Sales > Returns 中的商品退货不会通过 Vindi 退还资金。在 Vindi 控制面板中进行的退款会通过 charge_refunded webhook 到达，并被添加到备注中。订单状态不会自动更改。如有需要，请手动更新。

许可证密钥

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

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

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

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

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会移除许可证密钥和许可证状态。

故障排除

Vindi 没有出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，顾客是否使用 BRL 付款，Offered methods 中是否至少选择了一种方式，以及当前模式是否有 API 密钥：沙盒模式下为 Sandbox API key，正式模式下为 Live API key。若密钥缺失或店铺货币不是 BRL，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态或处于等待状态：Webhook 没有正常工作。请在 Vindi 中检查您所用账户（正式或沙盒）中是否存在该 webhook，其 URL 是否与设置中显示的完全一致（包括令牌），以及四个事件是否都已选中。

Webhook 返回 Forbidden：URL 中的令牌缺失或错误。请从设置中重新复制 URL。

Webhook 返回 Verification failed, retry later：无法通过 Vindi API 读取账单（例如该环境的 API 密钥已被删除），购物车在同一时刻正被另一请求更新，或无法设置订单状态。Vindi 会重新发送通知。日志会显示原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Vindi 的请求。

顾客看到 This payment method is temporarily unavailable：Vindi 拒绝了 API 密钥。请检查当前模式的密钥。

顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段。即使 Debug log 关闭，错误也会被记录。对于 boleto，账单地址必须包含街道、邮编、城市和州。

订单处于暂挂状态：请阅读 VibeFox Vindi Gateway 选项卡中的备注（参见订单状态），然后完成订单或退款。

切换到正式环境后，旧的沙盒订单：每笔付款都会保留其账单的环境。只要沙盒密钥仍在设置中，沙盒订单的检查、取消和退款就会继续使用沙盒密钥。

退款失败：请阅读消息。boleto 付款无法通过 Vindi 退款，且必须设置该付款所在环境的 API 密钥。若没有修改扩展的权限，选项卡会显示 You do not have permission to refund orders (modify this extension).

对开发人员：在创建 Vindi 顾客和账单之前，扩展会携带请求数据和订单触发 OpenCart 事件 wc_vdi_customer_request 和 wc_vdi_bill_request。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Vindi Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除在维护模式下放行 webhook 和付款状态页面的启动动作）。若 Delete data on uninstall 已开启，则其他设置（标题、描述、沙盒模式、API 密钥、付款方式、日志记录）、Webhook 令牌、商品缓存和日志都会被删除。若已关闭，这些设置会保留，供以后重新安装时使用。订单的 Vindi 账单和退款始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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