VibeFox Vindi for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
商店货币：巴西雷亚尔（BRL）。Vindi 仅以 BRL 收费，因此对于使用其他货币的购物车，将隐藏该付款方式。
Vindi 账户：您需要您的 Vindi 账户的 API 密钥。Vindi sandbox 是一个独立的 Vindi 测试账户，拥有自己的密钥。如果要提供 boleto、PIX 和 BolePix，还必须在您的 Vindi 账户中启用它们。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Vindi Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 粘贴 Sandbox API key，准备就绪后再粘贴 Live API key。选择 Offered methods。
5. 将设置中的 Webhook URL 复制到 Vindi 中（见「配置」）。
6. 开启 Enable / Disable 并点击 Save。在沙盒模式下测试一笔付款，然后关闭 Sandbox mode，以接受真实付款。
安装时，模块会创建两个订单状态：Awaiting Vindi payment 和 Vindi payment on hold。PrestaShop 会为所有货币、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中限制这些模块；在那里必须允许本模块使用 BRL。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Vindi Gateway > Configure。每个部分都有自己的 Save 按钮，该按钮会保存整个页面。在字段上方，当商店货币不是 BRL 或当前模式的 API 密钥为空时，页面会向您发出提示。在这两种情况下，结账时都不会显示该付款方式。保存时，密钥前后的空格会被去除。如果未选择任何付款方式，则会自动选中信用卡，页面显示 Choose at least one payment method — credit card was selected. 空的 Title 不会被保存：页面显示 Enter a title for the payment method.
Vindi
Enable / Disable：Enable Vindi payments 用于开启或关闭该付款方式。默认：关闭。
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：在 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 saved keys：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。
付款方式
Offered methods：顾客可以选择的付款方式。默认：信用卡。这些付款方式也必须在您的 Vindi 账户中启用。
Boleto、PIX 和 BolePix 需要顾客的 CPF 或 CNPJ，结账时会要求填写。
付款通知（Webhook）
Webhook 会告知您的商店某账单已付款、已取消、已被拒绝或已退款。本部分的 Webhook URL 字段会显示该 URL。启用友好 URL 时，它的形式为 https://your-shop/module/wcp_vindi_gateway/webhook?token=...，其中包含模块生成的密钥令牌。请按设置中显示的内容完整复制。在 Vindi 中进入 Settings > Webhooks，在正式账户和沙盒账户中分别添加此 URL，并选择以下事件：
Vindi 不对其通知进行签名，因此令牌缺失或错误的请求会被拒绝，并且每条通知都只会让模块在订单变更之前通过 Vindi API 重新读取账单。如果没有 Webhook，银行卡付款只有在顾客使用同一购物车再次下单时才会被识别（此时会找到已付款的账单并创建订单）；boleto 或 PIX 付款则要等顾客再次打开订单确认页面时才会被识别。
高级
Debug log：将 API 调用和通知记录到模块文件夹中的 logs/wc_vdi_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。密钥、Webhook 令牌和客户数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Delete data on uninstall：开启后，卸载模块时会删除设置、Webhook 令牌和日志。订单及订单的 Vindi 账单引用会被保留。默认：关闭。
结账
顾客选择付款方式（默认为 Vindi）。提供多种付款方式时，付款框会显示 Pay with 以及信用卡、boleto、PIX 或 BolePix 的选项。提供 boleto、PIX 或 BolePix 时，付款框还会有一个 CPF or CNPJ 字段。若未提供信用卡，该字段为必填；否则会显示 Required for boleto and PIX. 如果账单地址中的 Identification number 或 VAT 号码包含有效的 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 账单。在 Vindi 中，该账单会以 Order # 加购物车编号命名。
信用卡：顾客会被跳转到 Vindi 账单页面并在那里付款。此时尚未生成订单。Vindi 没有账单的返回 URL，因此顾客不会自动返回商店。订单会在 Vindi 通过 Webhook 确认付款后创建。如果顾客使用同一购物车再次下单，系统会再次提供待处理的账单；如果账单已经付款，则会立即创建订单。
Boleto、PIX 和 BolePix：账单会立即生成，订单以 Awaiting Vindi payment 状态创建，顾客会进入订单确认页面。在那里，以及顾客账户中的订单详情里，Payment 区域会显示 PIX 二维码、带 Copy code 按钮的复制粘贴 PIX 代码及其到期日期，以及一个 Open boleto 按钮。订单确认邮件包含 PIX 代码和 boleto 链接。如果 Vindi 未返回 boleto 或 PIX 数据，账单将被取消，顾客会看到一条错误信息。
只有在 Vindi 确认后，订单才会被标记为已付款：模块会通过 Vindi API 读取账单，并核对货币、账单是否属于该购物车（购物车编号和 Vindi 客户），以及已付金额是否等于订单总额。对于等待中的订单，订单确认页面最多每 15 秒通过 API 重新核查一次。付款收到后，页面会显示 Your payment with Vindi has been received. 当账单正在 Vindi 审核时，页面会显示 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.
对同一购物车的新付款尝试，如果付款方式、金额和环境均相同，则会复用待处理的 Vindi 账单。否则，在创建新账单之前会先在 Vindi 中取消之前的账单，因此顾客无法对同一购物车付款两次。如果之前的账单在此期间已付款，则会创建订单，且不会再开具新账单。
如果 Vindi 无法启动付款，顾客会停留在结账页面，并看到简短提示，例如检查 CPF / CNPJ、账单地址（办理 boleto 时需要街道、邮政编码、城市和州）、电子邮件或电话号码，或告知 Vindi 暂时不可用。技术原因会记录在日志中。
即使商店处于维护模式，Webhook 也会正常工作，并且不受商店国家限制的影响。
本模块仅接受单笔、一期付款。它不支持订阅或定期扣款、保存银行卡、分期付款，也不会在您的网站上显示银行卡表单：银行卡信息始终在 Vindi 页面输入。
订单与退款
订单状态
No order yet：银行卡付款已开始，但 Vindi 尚未确认。此时只存在购物车。
Awaiting Vindi payment：boleto、PIX 或 BolePix 付款正在等待（备注 Awaiting ... payment at Vindi.）。当 Vindi 报告账单已付款时，订单会变为 Payment accepted。
Payment accepted：付款已确认。该笔付款会以 Vindi 账单 ID 作为交易 ID 记录，并附带备注，显示 Vindi 账单、金额和环境。
Vindi payment on hold：Vindi 账单正在审核，已付账单与订单不符（货币、金额、购物车编号或 Vindi 客户），或账单是在订单被取消之后才付款的。备注会说明原因，并在订单上记录已付金额。请检查订单和库存，然后完成订单或退款。
Payment error：Vindi 拒绝了等待中订单的付款尝试。如果有的话，备注会显示收单机构的原因。顾客仍可支付同一账单，之后的付款会将订单变为 Payment accepted。
Canceled：等待中订单的账单已在 Vindi 中取消。在商店中取消订单时，其待处理的 Vindi 账单也会一并取消，因此无法再付款。如果无法取消，备注会提示您在 Vindi 后台取消该账单。
Refunded：该笔付款已通过模块全额退款。
如果为已付款的订单支付了第二张账单，订单不会改变。备注会提示您在 Vindi 中退还其中一笔付款。
Vindi 付款区块
订单页面会显示一个 Vindi payment 区块，其中包含 Vindi 账单和扣款、环境（沙盒付款会带有 Sandbox 标识）、付款方式、状态、已付和已退金额、退款记录、所有 Bills of this cart 以及该订单的 Vindi notes。
退款
在 Vindi payment 区块中输入金额（会自动填入尚未退还的金额），可选填写原因，然后点击 Refund via Vindi。确认询问 Refund this amount through Vindi? This cannot be undone. 支持对银行卡和 PIX 付款进行全额和部分退款。您需要具备编辑订单的权限；无需访问模块页面。退款金额仅限于 Vindi 实际收取的金额，因此在出现差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款所在的环境（正式或沙盒）中发送，因此该环境的 API 密钥必须已设置。全额退款还会在 Vindi 中取消账单，并将订单设为 Refunded；部分退款不会改变状态。退款成功后，会将 Vindi 扣款和状态一并添加到退款记录和备注中。如果 Vindi 或收单机构拒绝退款，该区块会显示错误，且不会记录任何退款。只有在 Vindi 报告账单已付款之后，才可以退款。
Vindi 无法退还 boleto 付款。该区块会显示 Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
模块不会开具贷项凭证（credit slip）。订单页面上的 PrestaShop 标准退款按钮不会通过 Vindi 退款。在 Vindi 后台完成的退款会通过 charge_refunded Webhook 送达，并添加到备注中。订单状态不会自动更改；如有需要，请在 PrestaShop 中以手动退款的方式记录。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Vindi Gateway 是 Modules > Module Manager > VibeFox Vindi Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-payment-vindi 一行和 Manage licenses and domains in your account 链接，该链接会打开您在 vibefox.net 上的账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最近一次已知状态运行。
一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Vindi。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 标签页中会出现提醒。现有订单不受影响：已生成的账单仍会通过 Vindi Webhook 得到确认，退款也照常运作。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间会自动重新检查状态：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Vindi：请检查许可证是否有效、Enable / Disable 是否已开启、购物车货币是否为 BRL、Offered methods 中是否至少选择了一种付款方式，以及当前模式是否设置了 API 密钥：沙盒模式需要 Sandbox API key，正式模式需要 Live API key。缺少密钥或货币不是 BRL 时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于 BRL、顾客所在国家以及顾客所属群组。
付款已完成，但未创建订单，或订单仍停留在 Awaiting Vindi payment：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 密钥。请检查当前模式的密钥。
顾客在下单时看到错误：请查看模块页面上的 Log 字段。即使 Debug log 处于关闭状态，错误也会被记录。对于 boleto，账单地址必须包含街道、邮政编码、城市和州。
订单为 Vindi payment on hold：请阅读 Vindi payment 区块中的备注（见「订单状态」），然后完成订单或退款。
切换到正式环境后出现旧的沙盒订单：每笔付款都会保留其账单的环境。只要沙盒密钥仍保留在设置中，沙盒订单的核查、取消和退款就会继续使用该密钥。
退款失败：请阅读提示信息。boleto 付款无法通过 Vindi 退款，并且必须设置该付款所在环境的 API 密钥。
卸载
进入 Modules > Module Manager，打开 VibeFox Vindi Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置、Webhook 令牌和日志都会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Vindi 账单和退款，以及订单状态 Awaiting Vindi payment 和 Vindi payment on hold 始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Vindi 是其各自所有者的商标。本模块与 Vindi 没有关联，也未获得 Vindi 的认可。