VibeFox Khipu for WooCommerce — 帮助

环境要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，并已安装且启用。没有 WooCommerce，插件将拒绝启用。

PHP：8.0 或更高版本。

商店货币：智利比索（CLP）、阿根廷比索（ARS）或秘鲁索尔（PEN）。当商店或在 Pay for order 页面上的订单使用其他货币时，该支付方式会在结账时隐藏。

Khipu 账户：您需要 Khipu 收款账户的 Receiver ID（“Id de cobrador”）、API key 和 secret key（“llave”）。您可以在 Khipu 账户的商户资料中找到它们（khipu.com/merchant/profile）。三者均为必填：没有 secret key，任何付款都无法被确认。

可访问的站点：Khipu 通过调用您的商店来确认付款，因此站点必须能从互联网访问（不能处于维护模式，不能有基本认证或防火墙阻止 Khipu）。

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

安装

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

2. 点击 Activate。

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

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

5. 输入您 Khipu 收款账户的 Receiver ID、API key 和 Secret key（参见“配置”）。

6. 开启 Enable / Disable 并保存。如需先测试，请使用 Khipu 开发者账户的密钥，然后再替换为您生产账户的密钥。

配置

所有设置都在同一个页面上：WooCommerce > Settings > Payments > Khipu。当缺少 Receiver ID、API key 或 secret key 时（此时结账时不会提供 Khipu），以及当商店货币不受支持时，页面会在字段上方给出警告。在支付方式列表中，在填写全部三个密钥之前，Khipu 会被标记为需要设置。

常规

Enable / Disable：Enable Khipu payments 用于开启或关闭该支付方式。默认：关闭。

Title：客户在结账时看到的支付方式名称。默认：Khipu。

Description：结账时显示在支付方式下方的文本。默认：Pay by bank transfer with Khipu。

Khipu 账户

请从您的 Khipu 收款账户复制 Receiver ID、API key 和 secret key（khipu.com/merchant/profile）。Khipu 没有单独的沙盒服务器，插件也没有测试模式开关。如需测试，请使用开发者（“desarrollo”）收款账户的密钥：它通过 DemoBank 测试银行付款，不会转移真实资金。正式上线时，请切换到您生产收款账户的密钥。

Receiver ID：您的 Khipu 收款人（“cobrador”）ID。来自其他 Khipu 账户的付款会被拒绝。

API key：用于创建付款，并向 Khipu 核实每一笔付款。

Secret key：用于验证 Khipu 付款通知的签名（HMAC-SHA256）。没有它，任何付款都无法被确认。

付款通知

Khipu 通过调用设置中这一部分显示的通知 URL 来确认付款。它的形式为 https://your-site/wc-api/webhook_wc_khipu/。该 URL 会随每笔付款自动发送，因此您的 Khipu 账户中无需任何配置，但该 URL 必须能从互联网访问。

每条通知都必须带有使用您的 Secret key 生成的有效签名。没有有效签名的通知会被拒绝。随后插件会向 Khipu 查询付款状态，并根据 Khipu 的报告采取行动：

Status after payment：Khipu 确认付款后的订单状态。状态会立即设置，只发生一次状态变更和一组邮件发送。

高级

Debug log：Log API calls and notifications，记录到 WooCommerce > Status > Logs，来源为 wcp_khipu_gateway。错误始终会被记录。密钥和付款人数据绝不会被写入。默认：关闭。

Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。订单数据（订单中的 Khipu 付款 ID）始终保留。默认：关闭。

结账

客户选择支付方式（默认为 Khipu）并下单。插件会以订单货币为订单总额创建一笔 Khipu 付款，其中包含订单号、商店名称和所订购的商品，并将客户引导至 Khipu 付款页面。账单邮箱有效时会传递给 Khipu。在 Khipu 页面上，客户通过自己银行的银行转账付款，并在那里选择 Khipu 提供的转账类型。

付款后，客户会返回到您商店的订单接收页面。只有在 Khipu 确认转账后，订单才会被标记为已付款：通过签名通知，或在客户打开订单接收页面时向 Khipu 查询状态。返回本身绝不会将订单标记为已付款。在转账尚未确认期间，页面会显示 Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

如果客户未付款就离开 Khipu 页面，客户会转到 Pay for order 页面，并看到 The Khipu payment was not completed. You can try again or choose another payment method. 重新尝试会删除之前未付款的 Khipu 付款，因此旧链接将无法再付款。如果 Khipu 已经收到之前的付款，订单会完成，且不会创建新的付款。如果之前的转账仍在核实中，客户会看到 Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

开启库存管理后，Khipu 付款会随 WooCommerce 的 Hold stock (minutes) 时间一起过期，因此客户无法为已取消的订单付款。

如果 Khipu 无法创建付款，客户会看到一条简短消息，例如 Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. 或 Khipu is temporarily unavailable. Please try again in a few minutes. 详细信息会写入日志。

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

该插件仅支持一次性银行转账付款。不支持从 WooCommerce 发起退款，也没有订阅、已保存的支付方式或预授权功能。

订单

订单状态

Pending payment：客户已被引导至 Khipu 且尚未付款，或 Khipu 尚未确认转账。订单备注中会显示 Khipu 付款 ID。

Processing 或 Completed：Khipu 已确认付款。状态遵循 Status after payment。订单备注中会显示 Khipu 付款 ID，交易 ID 即为 Khipu 付款 ID。

On hold：Khipu 报告了一笔金额或货币与订单不符的付款，或者付款在订单被取消之后才到达（例如超过保留库存时间之后）。订单备注会说明情况。请在您的 Khipu 账户中检查该笔付款，并完成订单或为客户退款。

如果付款到达时订单已付款，或在付款后已关闭，订单不会被更改。会有一条备注提示您：如果这是第二笔付款，请向客户退款。

退款

退款不会从 WooCommerce 发送到 Khipu。请从您的 Khipu 账户或通过银行转账为客户退款，然后在 WooCommerce 中手动记录该退款。

许可证密钥

该插件使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Khipu 的顶部。将密钥粘贴到 License key 并点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

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

没有有效密钥时，Khipu 不会在结账时向客户显示。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. 已登录的商店经理仍能看到该支付方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已经发起的付款仍会被确认。

许可证到期后，插件仍会继续工作，但更新和支持需要续订。状态会在后台自动再次检查。

故障排除

Khipu 未在结账时出现：请检查许可证是否有效、Enable / Disable 是否开启，以及 Receiver ID、API key 和 Secret key 是否都已填写。商店货币必须为 CLP、ARS 或 PEN。缺少任何一项时，设置页面会显示警告。

付款已完成，但订单仍为 Pending payment：Khipu 会在银行核实后确认转账。当 Khipu 通知到达或客户打开订单接收页面时，订单会更新。请检查您的站点在设置中显示的通知 URL 上能否从互联网访问（不能处于维护模式，不能有基本认证或防火墙阻止 Khipu），并查看 WooCommerce > Status > Logs，来源 wcp_khipu_gateway。

通知返回 Secret key not configured：Secret key 为空。请填写它。Khipu 会再次发送通知。

通知返回 Invalid signature、Missing signature 或 Malformed signature：Secret key 不属于您所使用密钥的那个收款账户，或者该请求并非来自 Khipu。

通知返回 Payment does not belong to this order：该付款是支付给其他 Receiver ID 或针对其他订单的。请检查 Receiver ID。

通知返回 Payment not final yet 或 Verification unavailable：转账仍在核实中，或无法连接到 Khipu。Khipu 会再次发送通知。

订单为 On hold：请阅读订单备注。金额或货币与订单不符，或者付款在订单被取消之后才到达。

客户看到“Khipu payments are not available right now”：API key 缺失或错误。请检查您 Khipu 账户中的密钥。

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

如果您的 Khipu 账户接受其他货币，例如 Khipu Spain 使用的 EUR，开发者可以通过过滤器 wc_khp_supported_currencies 添加它。

卸载

停用插件会保留所有数据。要移除它，请在 Plugins 页面停用并删除它。本插件的许可证密钥和许可证状态始终会被删除。仅当开启了 Delete data on uninstall 时，网关设置和日志才会被删除。否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。

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