VibeFox Windcave for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法激活。

PHP：8.0 或更高版本。

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

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

安装

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

2. 点击 Activate。

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

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

5. 输入您的 REST API 用户名和密钥：测试模式使用 UAT 凭据，真实付款使用正式环境凭据（参见“配置”）。

6. 选择交易类型和付款方式，开启 Enable/Disable 并保存。在开启 Test mode 的情况下进行一笔测试付款，然后关闭 Test mode，即可接受真实付款。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > Windcave。测试模式开启时，页面会显示 Test mode is on: payments go to the Windcave UAT environment and no real money is taken. 在付款方式列表中，在当前模式同时具备 API 用户名和 API 密钥之前，Windcave 会被标记为需要设置。插件版本显示在页面底部。

常规

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

Title：顾客在结账时看到的付款方式名称。默认：Credit/Debit Card (Windcave)。

Description：结账时显示在付款方式下方的文字。默认：You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

输入 Windcave 颁发的 REST API 凭据（用户名和 API 密钥，而非 PxPay 密钥）。正式环境和 UAT 凭据可以并排保存。测试模式只使用 UAT 凭据，正式模式只使用正式环境凭据。

Test mode：Use the Windcave UAT test environment (uat.windcave.com)。不会扣除真实款项。新的付款使用 UAT 凭据。退款和扣款始终发往订单付款时所在的环境。默认：关闭。

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 密钥。

付款

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

Purchase (capture immediately)：顾客付款时即扣款。

Auth (authorise now, capture later)：金额仅被预留。订单会被置为“保留”，您可以通过订单操作中的 Capture Windcave payment 进行扣款，也可以通过全额退款来释放预留金额。未扣款的授权会在几天后失效。

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

高级

Debug log：Log API requests and payment events。日志位于 WooCommerce > Status > Logs，来源为 wcp_windcave_payment_gateway。错误和警告始终会被记录；此选项会额外记录 API 请求和付款事件。API 密钥、银行卡信息和顾客个人数据都会被脱敏。默认：关闭。

Clean uninstall：Delete the plugin settings and logs when the plugin is deleted。订单上保存的付款数据（退款所需的 Windcave 交易 ID）始终会保留。默认：关闭。

通知 URL

您无需在 Windcave 中设置通知 URL。插件会在每个付款会话中发送其返回地址和通知地址。Windcave 会将通知（Fail-Proof Result Notification）发送至 https://your-site/wc-api/windcave_p_notification/。顾客的返回和通知都不是由 Windcave 签名的，因此插件从不单独信任它们：它始终使用创建该会话所在环境的凭据，通过 Windcave REST API 读取会话结果。

结账

顾客选择付款方式（默认为 Credit/Debit Card (Windcave)）并提交订单。插件会按订单金额和订单货币创建 Windcave 付款会话，并将顾客引导至 Windcave Hosted Payment Page。订单号作为商户参考号发送，同时发送的还有店铺语言以及顾客的姓名、电子邮件、电话和账单/收货地址。在测试模式下，结账区块会在付款方式下方显示 Test mode: payments go to the Windcave UAT environment, no real money is taken.

付款后，顾客会返回您店铺的订单接收页面。只有在 Windcave 确认后，订单才会被标记为已付款：无论顾客是否返回，还是 Windcave 通知到达，插件都会通过 Windcave REST API 查询会话结果。每个订单的锁定机制可确保付款只会生效一次。如果结果尚未确定，订单接收页面会再检查一次，并显示 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.

如果顾客返回时并未完成付款，结账页面（如果尝试是从 Pay for order 页面开始的，则为该页面）会显示以下消息之一：

Declined：您的付款被拒绝。请重试或选择其他付款方式。

Cancelled or expired：付款未在 Windcave 页面完成。您的订单已保存，您可以重试或选择其他付款方式。

Not confirmed yet：我们暂时无法确认您的付款。如果您已完成付款，请勿重复付款；Windcave 确认后，您将收到确认邮件。

Return could not be processed：我们无法处理您从付款页面的返回。如果您已被扣款，请在再次付款前与我们联系。

在顾客付款之前，购物车不会被清空，库存也不会被扣减。顾客可以重新支付未付款的订单，例如通过 Pay for order 页面。新的付款尝试会先检查之前的会话：如果已付款，则不会创建第二笔付款；如果顾客从未使用过付款页面且订单未发生变化，则会将顾客送回同一页面。如果此时之前的付款正在确认中，顾客会看到 Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

如果 Windcave 无法发起付款，顾客会看到一条简短消息：Windcave 无法使用此订单的详细信息发起付款，或付款服务暂时不可用。原因会被添加到订单备注中。如果当前模式没有凭据，顾客会看到 This payment method is not available at the moment. Please choose another payment method or contact us.

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

本插件不提供订阅或定期付款、已保存的银行卡、网站内嵌的银行卡表单（顾客始终在 Windcave 页面付款）、不支持 PxPay 2.0 API，也不会加收附加费。如果 Windcave 加收附加费，订单将与主交易进行匹配。

订单与退款

订单状态

Pending payment：顾客已被引导至 Windcave，但尚未付款，或 Windcave 尚未确认付款。如果顾客取消或会话过期，订单将保持“待付款”状态，并添加备注。

Processing or Completed：Purchase 付款已确认。WooCommerce 会照常将订单设置为“处理中”，对于无需配送的订单则设置为“已完成”。订单备注会显示金额、Windcave 交易 ID、授权码、银行卡类型（卡号已脱敏）以及环境（UAT 或正式环境）。订单的交易 ID 即为 Windcave 交易 ID。

On hold (authorised)：Auth 付款已获批准但尚未扣款。订单备注会说明如何扣款或释放。

On hold (does not match)：Windcave 报告的金额、货币、商户参考号或交易类型与订单不一致（例如，付款开始后订单被修改）。备注会列出差异。发货前请在 Windcave Payline 中核对付款，必要时进行退款。

Failed：付款被拒绝。备注会显示 Windcave 的响应文本和代码。顾客可以重试。

如果针对已取消的订单收到了已批准的付款，或针对已付款的订单收到了第二笔已批准的付款，订单不会被更改。附带交易 ID 的备注会提醒您在 Windcave Payline 中退款（或手动恢复已取消的订单）。

扣款（Auth 模式）

打开订单，在订单操作中选择 Capture Windcave payment，然后点击更新按钮。该操作仅出现在“保留”状态且授权尚未扣款或释放的订单上。将扣除订单的全部金额，扣款信息会添加到订单备注中，订单随后作为已付款订单继续处理（通常为“处理中”）。如果 Windcave 不接受扣款，订单页面会显示 Windcave capture failed: 并附上原因，原因同时会添加到订单备注中。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Windcave。支持全额和部分退款。退款会发送至付款时所在的环境（UAT 或正式环境）及其账户，因此必须保存该环境的凭据。退款成功后，会将其与 Windcave 交易 ID 一起添加到订单备注中。

对于未扣款的 Auth 付款，只能进行全额退款：这会释放（撤销）授权。部分金额会产生错误，提示您退还全额或先扣款。

如果 Windcave 拒绝退款，WooCommerce 会显示 Windcave declined the refund: 并附上原因，且不会记录退款。如果 Windcave 仍在处理退款，WooCommerce 会显示 Windcave has not confirmed the refund yet. See the order notes.，且不会记录退款。请在 Windcave Payline 中核对交易：如果已批准，请手动记录退款；否则请重试。同一退款的重复尝试不会向 Windcave 发送两次。在 Windcave Payline 中进行的退款不会同步到店铺。

许可证密钥

插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Windcave 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时，以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

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

没有有效密钥时，Windcave 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标有 (unlicensed — visible to admins only)，这样您可以在购买密钥之前设置并测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款和扣款也正常工作。

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

故障排除

Windcave does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否同时具备两项凭据：测试模式下为 UAT API username 和 UAT API key，正式模式下为 Production API username 和 Production API key。

The payment went through, but the order stays Pending payment：插件尚未能从 Windcave 获取结果。请打开订单备注：备注中会说明会话无法验证的时间和原因。请检查付款所在环境的凭据是否已保存且正确。当 Windcave 重新发送通知时（在能够验证结果之前，插件会返回错误，以便 Windcave 重试），以及顾客打开订单接收页面时，都会重新检查。您的服务器必须接受 Windcave 发送至 https://your-site/wc-api/windcave_p_notification/ 的请求。

Authentication failed in the order notes or the log：REST API 用户名或密钥有误，或属于另一环境。UAT 凭据仅适用于测试模式，正式凭据仅适用于正式模式。PxPay 密钥无法使用。

The customer sees that Windcave could not start the payment with the details of this order：Windcave 拒绝了会话请求，例如因为货币，或因为您的账户未启用某种付款方式。具体原因见订单备注和日志。

Order is On hold after payment：请阅读订单备注。要么该付款是等待扣款的 Auth 付款，要么已付金额、货币或商户参考号与订单不一致。请扣款、发货或退款。

Test payments and live payments：UAT 与正式环境是分开的。每个会话都会在其创建所在的环境中进行核实，退款和扣款会发送至付款所在的环境，即使您之后更改了 Test mode 设置也是如此。由插件 1.0 版本创建的订单使用旧版 API URL 设置所指定的环境。

Refund fails with a message about the environment：付款是在 UAT 或正式环境中完成的，但未保存该环境的凭据。请输入凭据后重试。

Capture Windcave payment is missing in the order actions：该操作仅对使用 Auth 付款且处于“保留”状态、尚未扣款或释放的订单显示。

Where to find details：错误和警告始终会写入 WooCommerce > Status > Logs，来源为 wcp_windcave_payment_gateway。开启 Debug log 后，还会记录 API 请求和付款事件。

The license block shows an error：请按照许可证区块中的提示操作。例如，如果该密钥已在另一域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用上一次已知的状态继续工作。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、插件选项和日志（包括日志文件（含轮转文件）和数据库日志条目）仅在开启了 Clean uninstall 时才会被删除。否则，它们会被保留，以便日后重新安装时使用。现有订单会保留其付款备注和 Windcave 交易 ID。

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