VibeFox Vindi for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，须已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
店铺货币：巴西雷亚尔（BRL）。Vindi 仅以 BRL 收款，因此对于其他货币，付款方式会被隐藏。
Vindi 账户：您需要自己 Vindi 账户的 API 密钥。Vindi sandbox 是一个单独的测试账户，拥有独立的密钥。如果您想提供 Boleto、PIX 和 BolePix，还必须在您的 Vindi 账户中启用这些方式。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，点击 Install Now，然后点击 Activate。您也可以通过 FTP 将 wcp_vindi_gateway 文件夹上传到 /wp-content/plugins/。
2. 打开设置页面：WooCommerce > Settings > Payments > Vindi > Manage，或在插件列表页面点击插件名称下方的 Settings。
3. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
4. 粘贴 Sandbox API key，准备好后再粘贴 Live API key。选择 Offered methods。
5. 将设置中的 Webhook URL 复制到 Vindi 中（参见「配置」）。
6. 启用 Enable / Disable 并保存。在测试环境中测试一笔付款，然后取消勾选 Sandbox mode，即可接受真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > Vindi。在字段上方，如果店铺货币不是 BRL，或当前模式的 API 密钥为空，页面会发出提醒。在这两种情况下，结账时都不会显示该付款方式。在付款方式列表中，在当前模式设置 API 密钥之前，Vindi 会被标记为需要设置。保存时，密钥会被去除首尾空格；如果未选择任何付款方式，则会自动选中信用卡，并且页面会显示 Choose at least one payment method — credit card was selected.
常规
Enable / Disable：Enable Vindi payments 用于开启或关闭该付款方式。默认值：off。
Title：结账时显示的付款方式名称。默认值：Vindi。
Description：结账时显示在付款方式下方的文字。默认值：Pay by credit card on the secure Vindi page, or by boleto / PIX。
API 密钥
请在 Vindi 控制面板的 Settings > API keys 中创建密钥：正式环境使用 app.vindi.com.br，测试环境使用 sandbox-app.vindi.com.br。每个订单都会记录其账单的创建环境，因此核查、取消和退款始终在该环境中进行。
Sandbox mode：Create new payments in the Vindi sandbox 会使用 sandbox-app.vindi.com.br 和测试环境的 API 密钥。顾客在结账时会看到 TEST MODE 提示：Vindi sandbox: no real charges. 默认值：on。取消勾选即可接受真实付款。
Live API key：正式 Vindi 账户的私钥。仅发送至 Vindi API。
Sandbox API key：Vindi 测试账户的私钥。
付款方式
Offered methods：顾客可以选择的付款方式。默认值：credit card。这些方式还必须在您的 Vindi 账户中启用。
付款通知（Webhook）
Webhook 用于通知您的店铺某张账单已付款、已取消或已退款。此设置区域会显示 Webhook URL。其格式类似 https://your-site/wc-api/webhook_wc_vindi/?token=...，并包含插件生成的密钥令牌。请完全按照设置中显示的内容复制。在 Vindi 中进入 Settings > Webhooks，正式账户和测试账户都要操作：添加此 URL，并选择以下事件：
令牌缺失或错误的请求会被拒绝。每条通知只会让插件在更新订单之前，通过 Vindi API 重新读取账单。如果没有 Webhook，银行卡、boleto 和 PIX 付款只有在顾客打开订单接收页面时才会被确认。
高级
Debug log：Log API calls and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_vindi_gateway。即使此选项关闭，错误和警告也始终会被记录。密钥和顾客数据从不记录。默认值：off。
Delete data on uninstall：Remove the settings, webhook token and logs when the plugin is deleted。默认值：off。
结账
顾客选择付款方式（默认为 Vindi）。当提供多种方式时，付款框会显示 Pay with，并可在信用卡、boleto、PIX 或 BolePix 之间选择。当提供 boleto、PIX 或 BolePix 时，付款框还会显示 CPF or CNPJ 字段。如果仅提供这些方式，该字段为必填；否则会显示 Required for boleto and PIX. 该号码会通过校验位进行验证。在经典结账中，如果启用了 Brazilian Market on WooCommerce，则不会显示该字段，因为该插件已经收集了 CPF / CNPJ。此时会使用该插件中的 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.
下单时，插件会根据账单信息为该订单创建一个 Vindi 客户，并按订单总额创建一张单期 Vindi 账单。
Credit card：顾客会被引导至 Vindi 账单页面并在那里付款。Vindi 没有账单的返回 URL，因此顾客不会自动返回店铺。订单通过 Webhook 确认，或在顾客打开订单接收页面时确认。在付款完成之前，该页面以及 My account 中的订单会显示 Your payment has not been completed yet. 和 Pay at Vindi 按钮。
Boleto、PIX 和 BolePix：账单会立即生成，订单设为「保留」状态，顾客会进入订单接收页面。在那里以及 My account > Orders 中，Payment 区域会显示 PIX 二维码、带有 Copy code 按钮的可复制粘贴 PIX 代码及其到期日期，以及 Open boleto 按钮。顾客的「保留」订单邮件和账单邮件包含 PIX 代码和 boleto 链接。
只有在 Vindi 确认后，订单才会被标记为已付款：插件会通过 Vindi API 读取账单，并检查该账单是否属于此订单（订单编号和 Vindi 客户），以及已付金额是否等于订单总额。
顾客可以通过 Pay for order 页面重新支付未付款的订单。如果付款方式、金额和环境均相同，则复用待处理的 Vindi 账单。否则，在创建新账单之前，会先在 Vindi 中取消旧账单，以防止顾客重复支付同一订单。如果之前的账单此时已被支付，则订单会被标记为已付款，并且不会创建新账单。
如果 Vindi 无法发起付款，顾客会看到简短的提示，例如请检查 CPF / CNPJ、账单地址、电子邮件或电话号码，或提示 Vindi 暂时不可用。如果此时同一订单正被另一请求处理，顾客会被要求稍等片刻后重试。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅接受单笔、一期付款。它不支持订阅或定期扣款、保存银行卡、分期付款，也不会在您的网站上显示银行卡表单：银行卡始终在 Vindi 页面输入。
订单与退款
订单状态
Pending payment：银行卡付款已开始，但 Vindi 尚未确认。
On hold：boleto、PIX 或 BolePix 付款正在等待（备注 Awaiting ... payment at Vindi.），或 Vindi 账单正在审核中。
Processing or Completed：付款已确认。状态按 WooCommerce 的标准方式设置：仅包含虚拟可下载商品的订单设为「处理中」或「已完成」。订单备注会显示 Vindi 账单、金额和环境。交易 ID 即为 Vindi 账单 ID。
On hold after payment：已付账单与订单不匹配（金额、订单编号或 Vindi 客户），或账单是在订单被取消之后才付款的。订单备注会说明原因。请检查订单和库存，然后完成订单或退款。
Failed：Vindi 拒绝了付款尝试。如有收单机构提供的原因，备注中会显示该原因。顾客仍可支付同一账单，之后的付款会完成订单。
Cancelled：账单已在 Vindi 中取消，或订单被您、顾客或 WooCommerce 库存保留超时取消。在店铺中取消订单时，其待处理的 Vindi 账单也会一并取消，因此无法再付款。如果无法取消，备注会提示您在 Vindi 控制面板中取消账单。在库存保留超时取消订单之前，会先检查账单：如果此时已被支付，则订单改为标记为已付款。
如果为已付款的订单再支付第二张账单，订单不会再次更改。备注会提示您在 Vindi 中退还其中一笔付款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Vindi。支持对银行卡和 PIX 付款进行全额和部分退款。全额退款还会在 Vindi 中取消账单。退款会在付款所在的环境（正式或测试）中发起，因此必须设置该环境的 API 密钥。退款成功后，会在订单备注中添加 Vindi 扣款记录和状态。如果 Vindi 或收单机构拒绝退款，WooCommerce 会显示错误，且不会记录任何退款。
Vindi 无法退还 boleto 付款。插件会显示 Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
在 Vindi 控制面板中完成的退款会通过 charge_refunded Webhook 送达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。如有需要，可在 WooCommerce 中创建手动退款，而不要使用 Refund via Vindi。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Vindi 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放该域名名额。请在您的 vibefox.net 账户中释放名额。
如果没有有效密钥，Vindi 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。插件列表页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Vindi 未在结账时显示：请检查许可证是否有效、Enable / Disable 是否已开启、店铺货币是否为 BRL、Offered methods 中是否至少选择了一种方式，以及当前模式是否已设置 API 密钥：测试模式使用 Sandbox API key，正式模式使用 Live API key。如果缺少密钥或货币不是 BRL，设置页面会显示警告。
付款已完成，但订单仍为 Pending payment 或 On hold：Webhook 未正常工作。请在 Vindi 中确认您所用账户（正式或测试）中存在该 Webhook，其 URL 与设置中显示的完全一致（包括令牌），并且四个事件均已选中。顾客打开订单接收页面时，订单也会被确认。
Webhook 返回 Forbidden：URL 中的令牌缺失或错误。请从设置中重新复制 URL。
Webhook 返回 Verification failed, retry later 或 Order busy, retry later：无法通过 Vindi API 读取账单（例如该环境的 API 密钥已被删除），或订单在同一时刻正被另一请求更新。Vindi 会重新发送通知。
顾客看到 This payment method is temporarily unavailable：Vindi 拒绝了 API 密钥。请检查当前模式的密钥。
顾客在下单时看到错误：请打开订单备注，或在 WooCommerce > Status > Logs 中查看来源为 wcp_vindi_gateway 的日志。即使 Debug log 关闭，错误也会被记录。对于 boleto，账单地址必须包含街道、邮政编码、城市和州。
付款后订单显示为 On hold：请阅读订单备注。已付金额、订单编号或 Vindi 客户与订单不符，或付款是在订单被取消之后到达的。请完成订单或退款。
切换到正式环境后，旧的测试订单：每个订单都保留其账单的环境。只要测试密钥仍在设置中，测试订单的核查、取消和退款就会继续使用该密钥。
退款失败：请阅读提示信息。boleto 付款无法通过 Vindi 退款，并且必须设置付款所在环境的 API 密钥。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后一次已知的状态运行。
卸载
停用插件会保留所有数据。如需删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、Webhook 令牌、插件的其他已存储数据和日志仅在 Delete data on uninstall 已开启时才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注、交易 ID 和 Vindi 数据。
Vindi 是其各自所有者的商标。本插件与 Vindi 没有关联，也未获得 Vindi 的认可或背书。