VibeFox Khipu for PrestaShop — 帮助

环境要求

PrestaShop： 8.0 至 9.x。

PHP： 8.0 或更高版本。模块会拒绝在更早的 PHP 版本上安装。

币种： 智利比索 (CLP)、阿根廷比索 (ARS) 或秘鲁索尔 (PEN)。对于其他币种的购物车，结账时会隐藏该支付方式。

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

可访问的商店： Khipu 通过调用您的商店来确认付款，因此通知 URL 必须可以从互联网访问，不能有密码保护，也不能有阻止 Khipu 的防火墙。商店的维护模式不会阻止它。

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Khipu Gateway 并点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，在 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

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

5. 开启 Enable / Disable，然后点击 Save。若要先进行测试，请使用 Khipu 开发者账户的密钥，之后再替换为您正式账户的密钥。

安装时，模块会创建订单状态 Khipu payment on hold。PrestaShop 会为所有币种、国家和客户组启用新的支付模块。您可以在 Payment > Preferences 中对其进行限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Khipu Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，当 Receiver ID、API key 或 Secret key 缺失时（此时结账时不会提供 Khipu），以及当商店的默认币种不受 Khipu 支持时，页面会向您发出警告。

Khipu

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

Title： 客户在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Khipu。必填。

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

Khipu 账户

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

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

API key： 用于创建付款，并在 Khipu 上验证每笔付款。

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

已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved secrets： 勾选 API key 或 Secret key，然后点击 Save 即可删除。空字段会保留已保存的值。

付款通知

Notification URL： Khipu 通过调用此处显示的 URL 来确认付款。启用友好 URL 后，它的样子是 https://your-shop/module/wcp_khipu_gateway/webhook，可能带有语言代码。每笔付款都会自动发送该 URL，因此您无需在 Khipu 账户中进行任何配置，但该 URL 必须可以从互联网访问。

每条通知都必须带有使用您的 Secret key 生成的有效签名。没有有效签名的通知会被拒绝。模块从不信任通知的内容：它会向 Khipu 查询付款状态，并根据 Khipu 报告的结果采取行动：

done： 转账已确认。在 Receiver ID、购物车和金额检查通过后创建订单。

done, reversed： 付款已被撤销。对于未付款的购物车，不会创建订单。已付款的订单会收到一条备注，其状态不变。

pending or verifying： 转账尚未最终完成。模块回复 “retry later”，Khipu 会再次发送通知。

Status after payment： Khipu 确认付款后订单的状态。状态会立即设置，并且只进行一次状态变更。

Processing： 订单获得 Payment accepted（默认）。

Completed： 订单获得 Delivered。

高级

Debug log： 将 API 调用和通知记录到模块文件夹中的 logs/wc_khp_debug.log.php。该文件无法通过网页打开。即使开关关闭，错误也始终会被记录。密钥和付款人数据从不写入。默认：关闭。

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

Delete data on uninstall： 开启时，卸载模块会删除网关设置和日志。订单数据（订单的 Khipu 付款 ID）始终保留。默认：关闭。

结账

在付款步骤中，客户会选择支付方式（默认为 Khipu）及其说明，然后确认订单。模块会按购物车币种为购物车总额创建一笔 Khipu 付款，并将客户带到 Khipu 付款页面。在 Khipu 中，该付款显示为 Order #，附带购物车编号和商店名称，以及商品列表。客户的邮箱（如果有效）会传递给 Khipu。在 Khipu 页面上，客户通过自己开户的银行进行银行转账。此时尚未创建订单。

付款后，客户返回您的商店。只有在 Khipu 确认后，订单才会被标记为已付款：通过签名通知确认，或在客户返回时向 Khipu 发出状态查询来确认。返回操作本身从不会将任何内容标记为已付款。订单创建后，客户会看到标准的订单确认页面。如果银行仍在核实转账，或无法连接 Khipu，则会显示 Payment confirmation 页面，内容为 Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail.，并带有 Check again 和 Back to checkout 按钮。如果购物车的最后一笔 Khipu 付款无法与之匹配（例如，它属于另一个 Receiver ID），客户会返回结账页面，并显示 We could not match this payment to an order. If you paid, please contact us.

如果客户离开 Khipu 页面而未付款，或付款未完成，客户会返回结账页面，并显示 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 无法创建付款，客户会留在结账页面，并看到简短提示，例如 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. 详细信息会写入日志。

即使商店处于维护模式，通知仍然有效，也不会受到您商店国家限制的阻挡。

该模块仅支持一次性银行转账付款。退款不会从 PrestaShop 发送到 Khipu，模块也不提供订阅、保存的支付方式或预授权功能。未付款的付款不会关联库存预留。

订单

订单状态

No order yet： 客户已被带到 Khipu 但尚未付款，或 Khipu 尚未确认转账。此时仅存在购物车。

Payment accepted or Delivered： Khipu 已确认付款。状态遵循 Status after payment。付款会以 Khipu 付款 ID 作为交易 ID 记录，并且备注会显示 Khipu payment verified. Payment ID:，同时附上付款 ID 和金额。

Khipu payment on hold： Khipu 确认了一笔金额或币种与订单不符的付款（例如，付款开始后购物车被修改），或者付款是在订单取消之后到达的。实际收到的金额会记录在订单上（币种不同时不记录），并附有备注进行说明。请在您的 Khipu 账户中核对该付款，然后完成订单或向客户退款。如果同一购物车随后收到金额正确的付款，订单将转为已付款状态。

如果某笔付款针对的是已付款或付款后已关闭的订单，订单不会被修改。备注会提示您，如果这是第二笔付款，请将其退还给客户。如果 Khipu 将一笔已付款的付款报告为已撤销，订单会收到一条备注，其状态不变。

Khipu 付款区块

订单页面会显示一个 Khipu payment 区块，其中包含该订单购物车的 Khipu 付款尝试（日期、金额、Khipu 付款 ID、Khipu 状态和结果）、订单处于 Khipu payment on hold 期间的 Manual review 警告，以及订单的 Khipu notes。该区块为只读。

退款

退款不会从 PrestaShop 发送到 Khipu，因为 Khipu 的 API 不提供退款功能。请从您的 Khipu 账户或通过银行转账向客户退款，然后在 PrestaShop 中手动记录退款。

许可证密钥

该模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Khipu Gateway 许可证区块位于 Modules > Module Manager > VibeFox Khipu Gateway > Configure 页面的设置上方，是第一个区块。在 License key 中输入密钥，然后点击 Activate。此后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除密钥）。其下方是 Product: presta-payment-khipu 一行和 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 账户中释放该名额。

没有有效的密钥时，结账时不会向客户显示 Khipu。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 标签页中会显示提醒。现有订单不受影响：已发起的付款仍会被确认。

许可证过期后，模块会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需配置计划任务（cron）。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 Khipu： 请检查许可证是否有效、Enable / Disable 是否已开启，以及 Receiver ID、API key 和 Secret key 是否都已填写。购物车币种必须是 CLP、ARS 或 PEN。缺少任何内容时，设置页面都会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、客户所在国家以及客户组。

付款已完成，但未创建订单： Khipu 在银行核实转账后才会确认。当 Khipu 通知到达或客户点击 Check again 时，订单才会创建。请检查您的商店能否在 Notification URL 中显示的 URL 处从互联网访问（不能有密码保护，也不能有阻止 Khipu 的防火墙），并查看模块页面上的 Log 字段。

通知返回 Secret key not configured： Secret key 为空。请输入该密钥。Khipu 会再次发送通知。

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

通知返回 Order not found 或 Payment does not belong to this order： 付款是转给另一个 Receiver ID 或针对另一个购物车的。请检查 Receiver ID。

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

通知返回 Busy, retry later 或 Order could not be created, retry later： 该订单在同一时刻正被另一个请求确认，或者订单无法创建（例如模块已被禁用）。Khipu 会再次发送通知。原因记录在日志中。

订单处于 Khipu payment on hold： 请阅读 Khipu payment 区块中的备注。金额或币种与订单不符，或者付款是在订单取消之后到达的。

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

如果您的 Khipu 账户接受其他币种，例如用于 Khipu 西班牙的 EUR，开发者可以使用 actionWcpKhipuSupportedCurrencies 钩子添加该币种。

卸载

进入 Modules > Module Manager，打开 VibeFox Khipu Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便以后重新安装。Khipu 付款尝试和订单状态 Khipu payment on hold 始终保留。现有订单会保留其付款备注和交易 ID。

Khipu 是其各自所有者的商标。本模块与 Khipu 没有关联，也未获得 Khipu 的认可。