VibeFox Windcave for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Windcave 账户：您需要一个带有 REST API 凭据的 Windcave 商户账户：一个 API 用户名和一个 API 密钥。Windcave 会分别为 UAT 测试环境（uat.windcave.com）和正式环境（sec.windcave.com）颁发凭据。请向 Windcave 支持或您的客户经理索取。PxPay 密钥无法用于本扩展。您希望提供的付款方式（银行卡、钱包及其他）必须已在您的 Windcave 账户中启用。

通知：您的店铺必须能够从互联网访问，以便 Windcave 发送付款通知。无需在 Windcave 中为此进行任何设置。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的 REST API 用户名和密钥：测试模式使用 UAT 凭据，正式付款使用正式环境凭据（参见 Configuration）。

5. 选择交易类型和付款方式，开启 Enable/Disable 并点击 Save。在 Test mode 开启时进行一次测试付款，然后关闭 Test mode 以接受真实付款。

OpenCart 4

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

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

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

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

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Windcave Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。测试模式开启时，页面会显示 Test mode is on: payments go to the Windcave UAT environment and no real money is taken. 如果已启用付款方式，但当前模式没有 API 用户名或密钥，页面会警告该付款方式在结账时被隐藏，例如 Windcave is enabled but the UAT API username / key are empty — the payment method is hidden at checkout. 如果您没有修改扩展的权限，页面只能查看设置，无法保存。

保存时，Title 不能为空，且长度不能超过 128 个字符（Enter a title for the payment method (at most 128 characters).）；Sort Order 必须是整数（Sort Order must be a whole number.）；Total 必须是大于或等于 0 的数字（Total: enter a number, 0 or greater.）；所选的地区和订单状态必须存在。否则不会保存任何内容，页面会显示错误。

Windcave

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

Title：顾客在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Credit/Debit Card (Windcave)。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中，确认按钮上方向顾客显示的文字。默认：You will be redirected to the secure Windcave payment page to complete your payment.

Sort Order：Windcave 在结账付款方式中的位置。可留空或输入整数；允许负数。

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

Total：订单必须达到的结账总额（以店铺默认货币计）才会提供 Windcave：0 或更大的数字。留空则对任何金额都提供。

Windcave REST API

输入 Windcave 颁发的 REST API 凭据（用户名和 API 密钥，而不是 PxPay 密钥）。正式和 UAT 凭据可以并排保存。测试模式只使用 UAT 凭据，正式模式只使用正式凭据。该部分包含指向 Windcave REST API 文档的链接。

Test mode：使用 Windcave UAT 测试环境（uat.windcave.com）。不会扣除真实款项。新的付款使用 UAT 凭据。退款和扣款始终使用订单付款时所在的环境。默认：off。

Production API username：sec.windcave.com 的 REST API 用户名。

Production API key：sec.windcave.com 的 REST API 密钥。

UAT API username：uat.windcave.com 的 REST API 用户名（测试模式）。

UAT API key：uat.windcave.com 的 REST API 密钥（测试模式）。

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

Notification URL：显示 Windcave 发送付款通知（Fail-Proof Result Notification）的地址。它由您 OpenCart 安装的前台地址生成，在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_windcave_payment_gateway/notify，在 OpenCart 4 中则形如 https://your-store/index.php?route=extension/wcp_windcave_payment_gateway/payment/wcp_windcave_payment_gateway.notify。Windcave 中无需做任何配置：扩展会在每个付款会话中发送其返回地址和此通知地址。该地址必须可从互联网访问，否则只有在顾客从 Windcave 返回时订单才会被确认。顾客的返回和通知都不是由 Windcave 签名的，因此扩展绝不会仅凭它们做出判断：它始终通过 Windcave REST API，使用创建该会话的环境的凭据来读取会话结果。

Payment

Transaction type：付款的收取方式。默认：Purchase。

Payment methods：Windcave 付款页面上显示的方式：Cards、Account2Account（新西兰银行转账）、Apple Pay、Google Pay、PayPal、Alipay、WeChat Pay、UnionPay、Interac、humm。可以选择多项。这些方式必须已在您的 Windcave 账户中启用。将该字段留空（Every method enabled on the account）即可显示账户中启用的所有方式。默认：Cards。

Orders

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

Order Status After Payment：在批准的 Purchase 或扣款之后设置。默认：Processing。

Windcave Payment On Hold Status：已授权但尚未扣款的 Auth 付款，或与订单不符的已批准付款（金额、货币、参考号）。备注会说明原因；发货前请检查。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：扩展不会设置此状态。对处于此状态的订单收到的已批准付款不会改变订单；备注会提示您在 Windcave Payline 中退款或恢复订单。默认：Canceled。

Refunded Status：在订单页面中付款被全额退款或授权被释放后设置。默认：Refunded。

Advanced

Debug log：将 API 请求和付款事件写入 OpenCart 日志文件夹（storage/logs）中的 windcave_p_debug.log.php。该文件无法通过网页打开。此项关闭时，只记录错误和警告。API 密钥、银行卡数据和顾客的个人数据永远不会被记录。默认：off。

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

Clean uninstall：卸载扩展时删除扩展的设置和日志。随订单保存的付款数据（退款所需的 Windcave 交易 ID）始终会被保留。默认：off。

扩展版本显示在该部分底部。

Import / Export

Export：Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit/Debit Card (Windcave)）。在 Confirm Order 步骤中，顾客会看到您的说明；在测试模式下，还会看到 Test mode: payments go to the Windcave UAT environment, no real money is taken. OpenCart 在此步骤创建订单，此时仍没有状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建 Windcave 付款会话，并将顾客转到 Windcave Hosted Payment Page。OpenCart 订单号会作为商户参考号发送，同时发送订单语言以及顾客的姓名、电子邮件、电话和账单地址（如果订单需要配送，还会发送配送地址）。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并在结账页面底部点击 Confirm Order。

付款后，顾客返回您的店铺。只有在 Windcave 确认后，订单才会被标记为已付款：扩展会在顾客返回时以及收到 Windcave 通知时，通过 Windcave REST API 查询该会话的结果。每个购物车的锁定机制可确保付款只会被应用一次。之后，订单会按照 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 订单成功页面，并显示 Your Windcave payment has been received. 对于被保留的订单（授权或与订单不符的付款），页面会显示 Your payment was received by Windcave. The store will check it before processing your order — please do not pay again.

如果顾客从已批准的付款返回，但结果尚未知晓，Payment confirmation 页面会显示 We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. 并提供 Check again 按钮。Windcave 确认付款后，通知会立即设置订单状态。

如果顾客在未完成付款的情况下返回，订单会保持没有状态，购物车会被保留，结账页面会显示以下消息之一：

在 OpenCart 4 中，这些消息会显示在结账页面上方。

顾客可以使用同一购物车重新尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 则会为结账保留一个订单并更新它，因此同一订单会在新的 Windcave 会话中付款）。新的尝试会先检查该购物车之前的会话：如果其中某个会话已付款，则应用该笔付款，顾客进入成功页面，并且不会再发起第二次付款；如果顾客从未使用过付款页面且订单没有变化，则会被送回同一页面。如果此时之前的付款正在确认中，顾客会看到 Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

如果 Windcave 无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方会显示提示：Windcave could not start the payment with the details of this order. Please check your billing details and try again, or choose another payment method. 或 The payment could not be started because the payment service is temporarily unavailable. Please try again in a moment or choose another payment method. 原因会写入日志。如果当前模式没有凭据，顾客会看到 This payment method is not available at the moment. Please choose another payment method or contact us.

在 OpenCart 4 中，如果结账中的订单在没有 Windcave 付款的情况下已获得状态，或者店铺期间已将其关闭，则下一次 Confirm Order 会将顾客送回结账页面，并在结账页面上方显示 This order can no longer be paid. Please check your cart and confirm the order again.，购物车将以新订单付款。如果结账中的订单已付款，但购物车此后有变化（包括新数量），顾客会被送回结账页面，新购物车将以新订单付款。

即使店铺处于维护模式，通知和顾客的返回仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展为其添加了启动动作。

本扩展不支持订阅或定期付款、保存的银行卡、您网站中嵌入的银行卡表单（顾客始终在 Windcave 页面上付款）、PxPay 2.0 API，也不会添加附加费。如果 Windcave 添加了附加费，订单会与主交易进行匹配。

订单与退款

Order statuses

无状态（缺失订单）：顾客已被转到 Windcave 但尚未付款，Windcave 尚未确认付款，或者付款被拒绝、取消或已过期。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：Purchase 付款已批准并与订单相符。备注会显示金额、交易 ID、授权码、银行卡类型（带掩码的卡号）以及环境（UAT 或正式）。

Windcave Payment On Hold Status，已授权（默认 Pending）：Auth 付款已批准但尚未扣款。备注会说明如何扣款或释放。

Windcave Payment On Hold Status，不符（默认 Pending）：Windcave 报告的金额、货币、商户参考号或交易类型与订单不同（例如付款开始后购物车在另一个标签页中被修改），或者订单已经被他人设置了状态。备注会列出差异。已批准的款项仍可以在订单选项卡中退款。发货前请在 Windcave Payline 中核对该付款，必要时予以退款。

Refunded Status（默认 Refunded）：付款已通过扩展全额退款，或授权已被释放。

如果已批准的付款到达一个处于 Cancelled Order Status 的订单，或者第二笔已批准的付款到达一个已付款的订单或购物车，则订单不会被修改。一条包含交易 ID 的备注会提示您在 Windcave Payline 中退款（或手动恢复已取消的订单）。

备注是订单 History 中的条目，顾客看不到。

VibeFox Windcave Payment Gateway tab

在 Sales > Orders 中打开一个通过 Windcave 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Windcave Payment Gateway 选项卡会显示 Transaction ID、Session ID、带有环境的 Type / status、Amount paid、Auth code / card、Capture transaction 或已释放的授权、Payment total / refunded、测试付款的 Test mode (UAT) 标签、扣款按钮、退款表单及其记录、Windcave sessions of this cart 以及订单的 Windcave notes。该选项卡只显示给有权访问本扩展的用户。

Capture (Auth mode)

对于处于 Windcave Payment On Hold Status 且授权尚未扣款或释放的订单，选项卡会显示 Capture Windcave payment。点击它并确认 Capture the authorised amount through Windcave now? 已授权的金额会被扣款，订单转为 Order Status After Payment，扣款交易会显示在选项卡中。如果 Windcave 不接受扣款，选项卡会显示 Windcave capture failed: 及原因，原因会添加到备注中，订单保持在保留状态。扣款需要修改扩展的权限，以及付款所在环境的凭据。

Refunds

在 VibeFox Windcave Payment Gateway 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Windcave。确认问题 Refund this amount through Windcave? This cannot be undone. 支持全额和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 Windcave 批准的金额和货币为基础计算，因此在出现差异后，您最多可以退还顾客实际支付的金额，而不是订单总额。扣款后的退款会针对扣款交易进行。退款会发送到付款所在的环境（UAT 或正式）及账户，因此必须已保存该环境的凭据。退款成功后，会连同 Windcave 交易 ID 一起添加到退款记录和备注中。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会把商品退回库存，与手动更改状态相同。部分退款不会改变状态。

对于未扣款的 Auth 付款，按钮为 Release authorisation (void)，且只能释放全部金额。部分金额会产生错误，提示您退还全部金额或先扣款。

如果 Windcave 拒绝退款，选项卡会显示 Windcave declined the refund: 及原因，且不会记录任何退款。如果 Windcave 仍在处理退款，选项卡会显示 Windcave has not confirmed the refund yet. See the order notes.，退款不会被记录。请在 Windcave Payline 中核对该交易：如果已批准，请手动记录退款；否则请重试。同一退款的重复尝试不会被发送到 Windcave 两次。

Sales > Returns 中的商品退货不会通过 Windcave 退款。在 Windcave Payline 中进行的退款不会通知店铺。

许可证密钥

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

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

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

没有有效的密钥时，结账时不会向顾客显示 Windcave。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户，仍会在店铺中看到该付款方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可关闭，并在 7 天内隐藏。现有订单不受影响：已发起的付款仍会通过通知或顾客返回得到确认，退款和扣款也仍可进行。

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

故障排除

结账时没有显示 Windcave：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否同时具有两项凭据：测试模式下为 UAT API username 和 UAT API key，正式模式下为 Production API username 和 Production API key。缺少时，设置页面会显示警告。另外还需确认付款地址位于所选的 Geo Zone 中，且订单达到了设置中的 Total。

付款已完成，但订单仍没有状态：扩展尚未能从 Windcave 获取结果。请查看扩展页面上的 Log 字段：错误始终会被记录，例如会话无法验证时。请检查付款所在环境的凭据是否已保存且正确。当 Windcave 重新发送通知（扩展会返回带错误代码的 payment could not be verified yet, retry later，以便 Windcave 重试）、顾客点击 Check again 以及顾客为同一购物车发起新付款时，都会重新检查。您的服务器必须接受 Windcave 发送到设置中显示的 Notification URL 的请求。

通知返回 order not found：该会话不是由本店铺创建的，例如使用同一 Windcave 账户的其他店铺的会话。该通知会被忽略。

日志中出现 Authentication failed：REST API 用户名或密钥错误，或属于另一个环境。UAT 凭据只在测试模式下有效，正式凭据只在正式模式下有效。PxPay 密钥无效。

顾客看到 Windcave 无法以此订单的详情发起付款：Windcave 拒绝了会话请求，例如因为货币或您账户中未启用的付款方式。具体原因在日志中。

顾客在 Confirm Order 之后看到 This payment method is not available.：结账会话已与订单不再匹配，或者付款方式在此期间已被关闭。顾客需要重新加载结账页面。

付款后订单处于审核状态：请阅读 VibeFox Windcave Payment Gateway 选项卡中的备注。付款可能是等待扣款的 Auth，或者已付金额、货币或商户参考号与订单不一致。请扣款、处理或退款。

测试付款与正式付款：UAT 和正式环境是分开的。每个会话都会在其创建所在的环境中进行检查，退款和扣款会进入付款所在的环境，即使您之后切换了 Test mode 也是如此。

退款失败，并显示与环境相关的消息：付款是在 UAT 或正式环境中完成的，而该环境的凭据未保存。请输入凭据后重试。

订单选项卡中缺少 Capture Windcave payment：该按钮仅在使用 Auth 付款、处于 Windcave Payment On Hold Status 且尚未扣款或释放的订单中显示；并且只有在付款环境的凭据已保存时，且仅对有权修改扩展的用户显示。

查找详细信息的位置：错误和警告始终会写入日志；开启 Debug log 可同时记录 API 请求和付款事件。

对开发者：在创建 Windcave 会话之前，扩展会触发 OpenCart 事件 windcave_p_session_request，并附带会话参数和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Windcave Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，重新安装时它们会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及在维护模式下放行通知和顾客返回的启动动作）。如果 Clean uninstall 已开启，则其他设置（标题、说明、测试模式、API 凭据、交易类型、付款方式、日志记录）和日志会被删除；如果关闭，则保留这些设置，供之后重新安装时使用。Windcave 的会话、交易和退款始终会被保留，因此重新安装后，之前已付款的订单仍可退款和扣款。现有订单会保留其付款备注。

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

Windcave 是其各自所有者的商标。本扩展与 Windcave 没有隶属关系，也未获得其认可。