VibeFox Windcave for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

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

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

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

安装

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

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Windcave Payment Gateway，然后点击 Configure。

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

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

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

安装时，模块会创建订单状态 Windcave payment on hold。PrestaShop 会为所有货币、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。测试模式开启时，页面会显示 Test mode 已开启：付款将进入 Windcave UAT 环境，不会扣除真实款项。 如果模块已启用，但当前模式没有 API 用户名或密钥，页面会提示该付款方式在结账时已隐藏，例如 Windcave 已启用，但 UAT API 用户名 / 密钥为空，该付款方式在结账时已隐藏。 Title 不能为空：此时页面会显示 请输入付款方式的名称。，且不会保存任何内容。

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 凭据，正式模式只使用正式环境凭据。本部分包含指向 Windcave REST API 文档的链接。

Test mode：使用 Windcave UAT 测试环境（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 密钥（测试模式）。

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

Clear saved keys：勾选 Production API key 或 UAT API key，然后点击 Save 即可删除。字段为空则保留已保存的值。

Notification URL：显示 Windcave 发送付款通知（Fail-Proof Result Notification）的地址。启用友好 URL 时，它类似于 https://your-shop/module/wcp_windcave_payment_gateway/notification。Windcave 端无需任何配置：模块会在每个付款会话中发送其返回地址和该通知地址。该地址必须可以从互联网访问，否则只有在顾客从 Windcave 返回时订单才会被确认。Windcave 不会对顾客的返回或通知进行签名，因此模块从不单独信任它们：它始终使用创建该会话的环境的凭据，通过 Windcave REST API 读取会话结果。

Payment

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

Purchase (capture immediately)：顾客付款时即收取款项。

Auth (authorise now, capture later)：仅预留款项。订单将进入 Windcave payment on hold 状态，您可以在订单的 Windcave 模块中通过 Capture Windcave payment 收取款项，也可以通过全额退款释放该预留。未扣款的授权会在几天后过期。

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

Advanced

Debug log：将 API 请求和付款事件记录到模块文件夹中的 logs/windcave_p_debug.log.php。该文件无法通过网页打开。关闭此选项时，只记录错误和警告。API 密钥、银行卡信息和顾客个人数据从不记录。默认：关闭。

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

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

模块版本显示在页面底部。

结账

在付款步骤中，顾客选择付款方式（默认为 Credit/Debit Card (Windcave)）及其说明。在测试模式下，顾客还会看到 Test mode：付款将进入 Windcave UAT 环境，不会扣除真实款项。 确认后，模块会按购物车金额和购物车货币创建 Windcave 付款会话，并将顾客引导至 Windcave Hosted Payment Page。购物车编号将作为商户参考号发送，同时发送店铺语言以及顾客的姓名、电子邮件、电话和账单地址（如果购物车需要配送，还会发送收货地址）。此时尚未生成订单。

付款后，顾客返回您的店铺。只有在 Windcave 确认付款后，订单才会被标记为已付款：无论是顾客返回时，还是 Windcave 通知到达时，模块都会通过 Windcave REST API 查询会话结果。每个购物车的锁定机制可确保付款只被处理一次。随后订单被创建，顾客会看到标准的订单确认页面，并显示 Your Windcave payment has been received. 对于处于保留状态的订单（授权或与购物车不符的付款），页面会显示 Your payment was received by Windcave. The shop 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 确认付款，通知就会创建订单。

如果顾客在未完成付款的情况下返回，结账页面会显示以下消息之一。购物车会被保留。

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

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

Not confirmed yet：我们尚无法确认您的付款。如果您已完成付款，请不要重复付款；Windcave 确认后，您将收到一封确认电子邮件。

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

顾客可以使用同一购物车重试。新的尝试会先检查之前的会话：如果已经付款，则创建订单，不会开始第二次付款；如果顾客从未使用付款页面且购物车没有变化，则会被送回同一页面。如果此时之前的付款正在确认中，顾客会看到 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.

即使店铺处于维护模式，通知依然有效，且不会被店铺的国家限制所阻止。

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

订单与退款

Order statuses

No order yet：顾客已被引导至 Windcave 但尚未付款，Windcave 尚未确认付款，或付款被拒绝、取消或过期。目前只存在购物车。

Payment accepted：Purchase 付款已确认且与购物车相符。付款会以 Windcave 交易 ID 记录，备注中显示金额、交易 ID、授权码、带掩码卡号的银行卡类型以及环境（UAT 或正式环境）。

Windcave payment on hold (authorised)：Auth 付款已获批准但尚未扣款。在扣款之前，订单上不会记录任何付款。备注说明了如何扣款或释放。

Windcave payment on hold (does not match)：Windcave 报告的金额、货币、商户参考号或交易类型与购物车不同（例如，付款开始后购物车在另一个标签页中被修改）。备注中列出了差异。对于购物车货币的 Purchase 付款，将以 Windcave 实际扣除的金额记录。发货前请在 Windcave Payline 中核对该付款，必要时予以退款。

Refunded：付款已全额退款，或授权已通过模块被释放。

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

Windcave payment block

订单页面会显示 Windcave payment 模块，其中包括交易 ID、会话 ID、交易类型和状态（含环境）、已付金额、授权码和银行卡、扣款或撤销交易、付款总额和已退款金额、测试付款的 Test mode (UAT) 标识、退款记录、购物车的所有 Windcave 会话以及订单的 Windcave notes。

Capture (Auth mode)

对于处于 Windcave payment on hold 状态且授权尚未扣款或释放的订单，该模块会显示 Capture Windcave payment 及金额。点击并确认 Capture the authorised amount through Windcave now? 后，将扣除已授权的金额（即订单总额，除非付款与订单不符），订单转为 Payment accepted，并以扣款交易 ID 记录付款。如果 Windcave 未接受扣款，模块会显示 Windcave capture failed: 及原因，该原因会添加到备注中，订单保持保留状态。

Refunds

在 Windcave payment 模块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Windcave。确认提示 Refund this amount through Windcave? This cannot be undone. 支持全额和部分退款。您需要有编辑订单的权限；无需访问模块页面。退款以 Windcave 批准的金额和货币为准，因此出现不符后，您最多只能退还顾客实际支付的金额，而非订单总额。扣款之后的退款会记在扣款交易上。退款会发送到付款所在的环境（UAT 或正式环境）及其账户，因此必须保存该环境的凭据。成功的退款会添加到退款记录和备注中，并附上 Windcave 交易 ID。全额退款会将订单设置为 Refunded。部分退款不会更改状态。

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

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

本模块不会生成退款凭证（credit slip）。订单页面上的 PrestaShop 标准退款按钮不会通过 Windcave 退款。在 Windcave Payline 中进行的退款不会通知到店铺。

许可证密钥

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

没有有效密钥时，结账时不会向顾客显示 Windcave。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会通过通知或顾客返回店铺得到确认，扣款和退款也照常进行。

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

故障排除

结账时不显示 Windcave：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否具备两项凭据：测试模式需要 UAT API username 和 UAT API key，正式模式需要 Production API username 和 Production API key。缺少这些凭据时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车货币、顾客所在国家和顾客所属群组。

付款已完成，但未创建订单：模块尚未能从 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 拒绝了会话请求，例如因为货币或您账户中未启用的付款方式。具体原因在日志中。

付款后订单处于 Windcave payment on hold：请阅读 Windcave payment 模块中的备注。要么付款是等待扣款的 Auth 授权，要么付款金额、货币或商户参考号与购物车不符。请扣款、发货或退款。

测试付款与正式付款：UAT 和正式环境是分开的。每个会话都在创建它的环境中进行核对，退款和扣款也发往付款所在的环境，即使您之后切换了 Test mode。

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

订单模块中缺少 Capture Windcave payment：该按钮仅显示在使用 Auth 付款、处于 Windcave payment on hold 状态且尚未扣款或释放的订单中，并且仅对有权编辑订单的员工显示。

详细信息在哪里：错误和警告始终会写入日志；开启 Debug log 还可记录 API 请求和付款事件。

卸载

进入 Modules > Module Manager，打开 VibeFox Windcave Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Clean uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便之后重新安装。Windcave 会话、交易和退款以及订单状态 Windcave payment on hold 始终保留，因此重新安装后，之前已付款的订单仍可退款和扣款。现有订单会保留其付款备注和交易 ID。

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