VibeFox CorvusPay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有它，插件将拒绝启用。

PHP：8.0 或更高版本。

币种：AUD、BAM、BHD、CAD、CHF、CZK、DKK、EUR、GBP、HRK、HUF、ISK、MKD、NOK、PLN、RON、RSD、RUB、SEK 或 USD。使用其他任何币种时，付款方式会在结账页面隐藏。金额以 2 位小数发送；小数位更多的总额（例如在使用 3 位小数的 BHD 店铺中）会被拒绝，而不是四舍五入。

CorvusPay 账户：您需要一个 CorvusPay 商户账户。CorvusPay 会为每个店铺分别发放 Store ID 和 Secret Key，测试店铺和正式店铺各有一套；它们显示在 CorvusPay Merchant Center 中。插件的 Success URL 和 Cancel URL 必须填入那里（参见「配置」）。

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

安装

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

2. 点击 Activate。

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

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

5. 输入您的 CorvusPay 测试店铺的 Store ID 和 Secret Key（如需正式收款，还要输入正式店铺的）。将设置页面上显示的 Success URL 和 Cancel URL 分别复制到 CorvusPay Merchant Center 中的测试店铺和正式店铺。

6. 开启 Enable/Disable，提交一个测试订单，然后取消勾选 Test Mode 以正式上线。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > CorvusPay。测试模式开启时，页面会在字段上方显示 Test mode is on.；当网关已启用但当前模式的 Store ID 或 Secret Key 为空时（此时在填写完成之前，该付款方式会在结账页面隐藏），以及店铺币种不被 CorvusPay 支持时，页面也会发出警告。

常规

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

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

Description：在结账页面显示于付款方式下方的文字。默认：Pay securely with your credit or debit card via CorvusPay。在测试模式下，会在其后追加 (Test mode — no real payment is taken.)。

店铺凭据

Store ID 和 Secret Key 由 CorvusPay 为每个店铺发放（测试和正式分别发放），并显示在 CorvusPay Merchant Center 中。

Test Mode：Enable test mode 使用 CorvusPay 测试环境（wallet.test.corvuspay.com）以及测试用的 Store ID 和 Secret Key。默认：开启。

Test Store ID：您的 CorvusPay 测试店铺的数字 Store ID。

Test Secret Key：您的 CorvusPay 测试店铺的 Secret Key，用于 HMAC-SHA256 签名。

Live Store ID：您的 CorvusPay 正式店铺的数字 Store ID。

Live Secret Key：您的 CorvusPay 正式店铺的 Secret Key，用于 HMAC-SHA256 签名。

Store ID 只能包含数字。如果输入其他内容，会显示错误并保留之前的值。付款始终使用其发生所在店铺的 Secret Key 进行验证，因此在仍有未完成的测试订单时，请保持测试密钥处于填写状态。

Success URL 和 Cancel URL

将本部分显示的两个地址分别复制到 CorvusPay Merchant Center 中的测试店铺和正式店铺。付款后，CorvusPay 会将顾客送回这两个地址。

Success URL：形如 https://your-site/wc-api/corvuspay_payment_success/。CorvusPay 会对此请求签名；只有签名验证通过后，订单才会标记为已付款。

Cancel URL：形如 https://your-site/wc-api/corvuspay_payment_cancel/。CorvusPay 不会对其签名，因此它只能取消持有本店铺所发 CorvusPay 订单号的未付款订单。

付款

Transaction Type：银行卡的扣款方式。

Sale (capture immediately)：立即向银行卡扣款（默认）。

Authorize only (capture in Merchant Center)：仅预留金额。订单被设为保留状态；您在 CorvusPay Merchant Center 中对该笔付款进行扣款（完成付款），然后将订单设为处理中。

Payment Page Language：CorvusPay 支付页面的语言。Site language（默认）在 CorvusPay 支持时使用您网站的当前语言，否则使用英语。您也可以选择克罗地亚语、英语、德语、意大利语、塞尔维亚语或斯洛文尼亚语。

Order Status After Payment：Sale 付款成功后订单的状态。状态会立即设置，不会再进行第二次状态变更。

Processing (WooCommerce default)：默认。

Completed：每个已付款订单都变为已完成。

On Hold：每个已付款订单都等待您手动审核。

高级

Logging：Enable debug logging 会写入 WooCommerce > Status > Logs，来源为 wcp_corvuspay_gateway。错误始终会被记录；密钥和顾客数据则绝不会记录。默认：关闭。

Delete Data：Delete the plugin settings and log files when the plugin is deleted (uninstalled)。停用插件绝不会删除任何内容。订单上保存的付款数据始终会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Credit/Debit Card (CorvusPay)）并下单。订单保持待付款状态，Pay for order 页面显示 Redirecting to CorvusPay for payment. Please wait...，并将已签名的表单发送到 CorvusPay 支付页面。如果跳转没有开始，顾客点击 Pay via CorvusPay。系统会发送订单总额、币种、简短的购物车描述以及账单信息（用于预填支付页面）。只要金额不变，就会重复使用同一个 CorvusPay 订单号，CorvusPay 不接受针对该订单号的第二次付款。

付款后，CorvusPay 会将顾客送回 Success URL。只有 CorvusPay 确认后，订单才会标记为已付款：CorvusPay 订单号必须是为此订单发放的，签名必须与付款所在店铺的 Secret Key 匹配，金额和币种也必须与订单一致。随后顾客会进入订单已接收页面。库存在付款确认时减少，购物车在订单已接收页面清空。

如果顾客在 CorvusPay 页面取消，未付款订单会被取消，顾客将带着完好的购物车返回结账页面，并看到 The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method.。如果付款是从 Pay for order 页面发起的且购物车为空，WooCommerce 会在购物车页面显示 The CorvusPay payment was cancelled and the order was not paid.。如果无法验证 Success URL 请求，顾客会看到 We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again.，订单不会被更改。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。文字已翻译为克罗地亚语。

只有 CorvusPay 将顾客送回 Success URL 时，订单才会被确认；没有服务器到服务器的通知。如果顾客在付款后立即关闭浏览器，订单会保持待付款状态。本插件不支持在 WooCommerce 中退款、扣款（capture）或撤销（void）（CorvusPay 服务器 API 需要客户端证书），也不支持保存银行卡、订阅、分期付款、IBAN / PIS 或 CorvusWallet。

订单

订单状态

Pending payment：顾客已被转到 CorvusPay，但尚未返回。如果顾客已付款但没有返回，请在 CorvusPay Merchant Center 中核对该笔付款，并手动完成订单。

Processing、Completed 或 On Hold：Sale 付款已确认。状态取决于 Order Status After Payment。订单备注会显示 CorvusPay 订单号、授权码和卡类型。订单的交易 ID 为 CorvusPay 交易 ID；如果 CorvusPay 未提供，则为 CorvusPay 订单号，可凭此在 Merchant Center 中找到该笔付款。

On hold，已授权：已选择 Authorize only。请在 CorvusPay Merchant Center 中扣款，然后将订单设为处理中。

On hold，金额/币种不一致：已付金额或币种与订单不一致。在 CorvusPay Merchant Center 中核实付款之前，请勿发货。

On hold，已取消订单的付款：订单被取消之后（例如因未付款订单超时）又收到了一笔成功的付款。请履行该订单，或在 CorvusPay Merchant Center 中退还该笔付款。

Cancelled：顾客在 CorvusPay 页面取消了付款。

如果已付款或已关闭的订单又收到另一笔不同的成功付款，订单不会被更改。备注会提示您检查 CorvusPay Merchant Center，并在必要时退还重复的付款。

Refunds：不支持在 WooCommerce 中退款、扣款和撤销。请在 CorvusPay Merchant Center 中操作，并在 WooCommerce 中手动记录退款。

许可证密钥

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

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

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

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

故障排除

CorvusPay 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Store ID 和 Secret Key 是否已填写（测试模式下为 Test Store ID 和 Test Secret Key，正式模式下为 Live Store ID 和 Live Secret Key），以及店铺币种是否被 CorvusPay 支持。设置页面在每种情况下都会显示警告。

付款已完成，但订单仍为待付款：很可能是 Success URL 没有填入 CorvusPay Merchant Center，或 WooCommerce 中的 Secret Key 与店铺不匹配。开启 Logging，并在 WooCommerce > Status > Logs 中来源为 wcp_corvuspay_gateway 的日志里查找 INVALID signature。如果顾客在返回之前关闭了浏览器，订单同样会保持待付款；此时请在 Merchant Center 中核对付款，并手动完成订单。

顾客看到 We could not confirm this CorvusPay payment：Success URL 请求被拒绝：缺少必填字段、CorvusPay 订单号不是为该订单发放的、该店铺的 Secret Key 为空，或签名不匹配。订单不会被更改。日志中会显示原因。

顾客看到 This order total cannot be paid via CorvusPay：总额为零，或小数位超过 2 位。

顾客看到 CorvusPay is not configured 或 CorvusPay does not accept payments in …：当前模式的 Store ID 或 Secret Key 缺失，或订单币种不受支持。

订单处于 On hold：请阅读订单备注。可能是已选择 Authorize only，已付金额或币种与订单不一致，或付款是在订单被取消之后到达的。

许可证区块显示错误：请按区块中的提示操作。例如，如果密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址发生了变化，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会按最近一次已知的状态继续工作。

卸载

停用插件会保留所有数据。如需移除，请在 Plugins 页面中先停用再删除。本插件的许可证密钥和许可证状态始终会被移除。网关设置和日志文件仅在 Delete Data 已开启时才会被移除，否则会保留，以便日后重新安装。订单上保存的付款数据始终会保留。现有订单会保留其付款备注和交易 ID。

CorvusPay 是其各自所有者的商标。本插件与 CorvusPay 没有关联，也未获得 CorvusPay 的认可。