VibeFox Khipu for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：智利比索（CLP）、阿根廷比索（ARS）或秘鲁索尔（PEN）。该货币必须存在于 System > Localisation > Currencies 中。只有当客户使用这些货币之一付款时才会提供 Khipu；对于其他货币，结账时会隐藏该付款方式。

Khipu 账户：您需要 Khipu 收款账户的 Receiver ID（"Id de cobrador"）、API key 和 secret key。您可以在 Khipu 账户的商户资料下找到它们（khipu.com/merchant/profile）。三者均为必需：缺少任一项，结账时都不会提供 Khipu；缺少 secret key 则无法确认任何付款。无需在 Khipu 账户中进行任何设置。

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

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

安装

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

OpenCart 3

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

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

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

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

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

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_khipu_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

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

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

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

新安装时，付款方式默认为关闭。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit。左侧列出各个部分；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在 Receiver ID、API key 或 secret key 缺失时发出警告（此时结账页面不会提供 Khipu），并在商店默认货币不受 Khipu 支持时发出警告（此时仅当客户使用 CLP、ARS 或 PEN 付款时才提供 Khipu）。如果您没有修改扩展的权限，页面只显示设置，无法保存。

保存时，Title 不能为空或超过 128 个字符，Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且地理区域和订单状态必须存在。否则不会保存任何内容，页面会指出具体字段。缺少密钥不会阻止保存。

Khipu

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

Title：客户在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Khipu。必填，1 到 128 个字符。

Description：在 Confirm Order 步骤中显示给客户的文字，位于确认按钮上方。默认：通过 Khipu 银行转账付款。

Sort Order：Khipu 在结账付款方式中的位置。留空或输入整数。

Geo Zone：仅对所选地理区域中的付款地址提供 Khipu。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单需要达到的结账总额（以商店默认货币计）才会提供 Khipu。留空则对任何金额都提供 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）。没有它，任何付款都无法确认。

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

付款通知

Notification URL：Khipu 通过调用此处显示的 URL 来确认付款。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook；在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook，由您 OpenCart 安装的前台地址生成。每次付款都会自动发送该 URL，因此无需在 Khipu 账户中进行任何配置，但该 URL 必须能从互联网访问。

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

done：转账已确认。订单在通过 Receiver ID、付款尝试和金额检查后获得其状态。

done, reversed：付款已被撤销。未付款的订单不会获得状态。已付款的订单会获得一条备注，其状态不变。

pending 或 verifying：转账尚未最终完成。扩展回复 "retry later"，Khipu 会再次发送通知。

Status after payment：Khipu 确认付款后订单获得的状态。该状态会通过一次状态变更立即设置。

Processing：订单获得 Paid Order Status（默认）。

Completed：订单获得 Complete Order Status。

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Khipu 确认付款之后，订单才会获得状态。下面的每个字段都列出您的 OpenCart 订单状态。

Paid Order Status：当 Status after payment 为 Processing 时，确认付款后的状态。默认：处理中。

Complete Order Status：当 Status after payment 为 Completed 时，确认付款后的状态。默认：已完成。

On Hold (Review) Status：金额或货币与订单不符的付款，或在订单取消后才到达的付款，会获得此状态以及说明原因的备注。默认：待付款，因为 OpenCart 没有“保留”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

高级

Debug log：将 API 调用和通知记录到 OpenCart 日志文件夹（storage/logs）中的 wc_khp_debug.log.php。该文件无法通过网页打开；当其达到 5 MB 时，会被移动到 wc_khp_debug.old.log.php。即使开关关闭，错误也会始终被记录。密钥和付款人数据从不写入。默认：关闭。

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

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

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API key 和 secret key 不会被导出。

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

结账

在 Payment Method 步骤中，客户选择付款方式（默认为 Khipu）。在 Confirm Order 步骤中，客户会在确认按钮上方看到您的说明。OpenCart 在此步骤创建订单，此时仍无状态。当客户点击 Confirm Order 时，扩展会以订单货币为订单总额创建一笔 Khipu 付款，并将客户带到 Khipu 付款页面。在 Khipu 上，该付款会显示为 Order # 加订单号和商店名称，并附带商品列表。客户的电子邮件（如果有效）会传递给 Khipu。在 Khipu 页面上，客户通过自己银行的银行转账付款。

在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。

付款后，客户会返回您的商店。只有在 Khipu 确认后，订单才会被标记为已付款：通过带签名的通知，或在客户返回时向 Khipu 发出状态查询。返回本身绝不会将任何内容标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，发送常规的订单邮件并更新库存，客户会看到 OpenCart 的订单成功页面。如果银行仍在核实转账，或无法连接 Khipu，则会显示 Payment confirmation 页面，内容为 Khipu is confirming your bank transfer. Your order will be confirmed 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. 购物车会被保留。在 OpenCart 4 中，这些提示显示在结账页面上方。每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账的订单，并用新的 Khipu 付款支付它）都会删除该订单或购物车之前未付款的 Khipu 付款，因此旧链接将无法再付款。如果 Khipu 已收到之前的付款，则会应用该付款，客户进入成功页面，无需新的付款。如果之前的转账仍在银行核实中，客户会看到 Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. 如果之前的付款处于审核中，则会要求客户在再次付款前联系商店。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如您取消了订单），客户会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 如果订单已经生成且购物车此后已变化，提示为 Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. 两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。

如果 Khipu 无法创建付款，客户会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 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. 详细信息会写入日志。

商店处于维护模式时，通知也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作，放行通知和客户的返回请求。

该扩展仅接受一次性银行转账付款。退款不会由 OpenCart 发送给 Khipu，并且不支持订阅、已保存的付款方式或预授权。未付款的付款不会占用库存。

订单

订单状态

无状态（缺失订单）：客户已被送至 Khipu 但尚未付款，或 Khipu 尚未确认转账。在 Sales > Orders 中，这类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Paid Order Status 或 Complete Order Status（默认处理中或已完成）：Khipu 已确认付款。状态遵循 Status after payment。备注会显示 Khipu payment verified. Payment ID: 以及付款 ID 和金额。

On Hold (Review) Status（默认待付款）：Khipu 确认了一笔金额或货币与订单不符的付款，或付款是在订单被取消或拒绝之后到达的。备注会对此加以说明。请在您的 Khipu 账户中检查该付款，然后完成订单或向客户退款。如果之后同一订单收到金额正确的付款，订单将转为已付款状态，并通过电子邮件通知客户。如果付款是在订单已转入其他处理状态之后到达的，状态不会改变，只会添加一条备注。

如果某个已付款的订单，或已付款购物车中的另一订单收到付款，订单不会被更改。如果这是第二笔付款，备注会请您将其退还给客户。如果 Khipu 将已付款的付款报告为已撤销，订单会获得一条备注，其状态不会改变。

备注是订单 History 中的条目，客户看不到。备注以 Khipu 一词开头。

VibeFox Khipu Gateway 选项卡

在 Sales > Orders 中打开一个使用 Khipu 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Khipu Gateway 选项卡会显示该订单的 Khipu 付款尝试（日期、金额、Khipu 付款 ID、Khipu 状态和结果）；订单处于审核状态时会显示 Manual review 警告；此外还有该订单的 Khipu notes。该选项卡为只读，并对有权访问扩展的用户显示。

退款

退款不会由 OpenCart 发送给 Khipu，因为 Khipu 的 API 不提供退款功能。该选项卡会说明这一点。请通过您的 Khipu 账户或银行转账向客户退款，然后在 OpenCart 中手动更改订单状态。

许可证密钥

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

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

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

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

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

故障排除

结账时不显示 Khipu：请检查许可证是否有效、Enable / Disable 是否开启，以及 Receiver ID、API key 和 Secret key 是否全部已填写。客户必须使用 CLP、ARS 或 PEN 付款。设置页面在缺少任何内容时会显示警告。另请检查付款地址是否位于所选 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Khipu 会在银行核实转账之后才确认。订单会在 Khipu 通知到达或客户点击 Check again 时获得其状态。请确认您的商店可以从互联网通过 Notification URL 中显示的地址访问（不能有密码保护，也不能有防火墙阻止 Khipu），并查看扩展页面上的 Log 字段。

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

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

通知返回 Order not found、Payment not found for this account 或 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 updated, retry later：订单在同一时刻正被另一请求确认，或无法设置订单状态。Khipu 会再次发送通知。原因记录在日志中。

订单在付款后处于审核状态：请阅读 VibeFox Khipu Gateway 选项卡中的备注。金额或货币与订单不符，或付款是在订单取消之后到达的。

客户看到 "Khipu payments are not available right now"：API key 缺失或有误。请在 Khipu 账户中检查密钥。

对于开发者：扩展会触发 OpenCart 事件 wc_khp_supported_currencies（用于添加您的 Khipu 账户接受的货币，例如适用于 Khipu 西班牙的 EUR）、wc_khp_currency_decimals 和 wc_khp_payment_data。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Khipu Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及三个订单状态，这些设置在重新安装后会恢复为默认值。在 OpenCart 4 中，其事件和启动动作（该动作在维护模式下放行通知和客户的返回请求）也会被删除。如果 Delete data on uninstall 已开启，则其余的网关设置（标题、说明、Receiver ID、密钥、付款后状态、调试日志）和日志都会被删除；如果关闭，则会保留，以便日后重新安装时使用。Khipu 付款尝试记录始终保留，因此即使重新安装后，之前已付款订单的迟到通知仍会被处理。现有订单会保留其付款备注。

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

Khipu 是其各自所有者的商标。本扩展与 Khipu 无关，也未获得 Khipu 的认可或背书。