VibeFox CorvusPay for PrestaShop — 帮助

要求

PrestaShop：8.0 至 9.x。

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

货币：AUD、BAM、BHD、CAD、CHF、CZK、DKK、EUR、GBP、HRK、HUF、ISK、MKD、NOK、PLN、RON、RSD、RUB、SEK 或 USD。购物车使用其他货币时，结账时不显示该付款方式。金额以 2 位小数发送；小数位更多的总额（例如在 BHD 价格为 3 位小数的商店中）会被拒绝，而不是四舍五入。

CorvusPay 账户：您需要一个 CorvusPay 商户账户。CorvusPay 为每个商店分别颁发 Store ID 和 Secret Key，测试商店与正式商店分开；它们显示在 CorvusPay Merchant Center 中。模块的 Success URL 和 Cancel URL 必须填写在那里（见“配置”）。

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

安装

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

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

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

4. 输入 CorvusPay 测试商店的 Store ID 和 Secret Key（用于正式付款时，还需输入正式商店的 Store ID 和 Secret Key）。将 Configure 页面显示的 Success URL 和 Cancel URL 复制到 CorvusPay Merchant Center，测试商店和正式商店都要填写。

5. 开启 Enable/Disable 并点击 Save。下一笔测试订单，然后关闭 Test Mode 以正式上线。

安装时，模块会创建订单状态 CorvusPay payment on hold。PrestaShop 会将新的付款模块与当时启用的货币、客户群组和国家/地区关联。您可以在 Payment > Preferences 中修改此设置；之后启用的国家/地区必须在那里为该模块勾选。

配置

所有设置都在模块页面上：Modules > Module Manager > VibeFox CorvusPay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会在测试模式开启时显示 测试模式已开启。付款将进入 CorvusPay 测试环境——不会扣除真实款项。；当支付网关已启用，但当前模式的 Store ID 或 Secret Key 为空时（此时在结账时隐藏，直到填写完整），页面会发出警告；当商店的默认货币不受 CorvusPay 支持时，页面也会发出警告。

CorvusPay

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

Title: 顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit/Debit Card (CorvusPay)。

Description: 结账时付款方式下方显示的文字。默认：Pay securely with your credit or debit card via CorvusPay。测试模式下会添加 （测试模式——不收取真实付款。）。

商店凭证

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

Test Mode: 使用 CorvusPay 测试环境（wallet.test.corvuspay.com）以及测试 Store ID 和测试 Secret Key。默认：开启。关闭后，将通过 wallet.corvuspay.com 接收真实付款。

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 签名。

Clear saved secrets: 勾选 Test Secret Key 或 Live Secret Key，然后点击 Save 将其删除。

Store ID 只能包含数字。如果输入其他内容，页面会显示 … 只能包含数字——已保留之前的值。，但其他字段仍会保存。已保存的 Secret Key 不会再次显示：该字段保持为空，并显示 已保存——留空即可保留。 只有需要更改时才输入新值。付款始终使用发起付款的商店的 Secret Key 进行验证，因此在测试付款仍可能返回期间，请保持测试密钥已填写。

Success URL 和 Cancel URL

将本节显示的两个地址复制到 CorvusPay Merchant Center，测试商店和正式商店都要填写。付款后，CorvusPay 会将顾客带回这些地址。请按页面显示的内容原样复制；使用友好 URL 时，它们看起来类似下面的示例，可能带有语言代码，如 /en/。

Success URL: 形如 https://your-shop/module/wcp_corvuspay_gateway/success。CorvusPay 会对该请求签名；只有签名验证通过后才会创建订单。

Cancel URL: 形如 https://your-shop/module/wcp_corvuspay_gateway/cancel。CorvusPay 不对其签名，因此它只能将本商店颁发的 CorvusPay 订单号对应的未付款付款尝试标记为已取消。

付款

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

Sale (capture immediately): 立即扣款（默认）。

Authorize only (capture in Merchant Center): 仅预留金额。订单将进入 CorvusPay payment on hold；您需在 CorvusPay Merchant Center 中扣款（完成）付款，然后将订单设为 Payment accepted。

Payment Page Language: CorvusPay 付款页面的语言。Site language（默认）在 CorvusPay 支持时使用商店当前语言，否则使用英语。您还可以选择 Hrvatski、English、Deutsch、Italiano、Srpski 或 Slovenščina。

Order Status After Payment: Sale 付款成功后的订单状态。订单将直接以此状态创建。

Payment accepted (default): PrestaShop 对已付款订单的标准状态。

Delivered (completed): 每个已付款订单都会变为已送达。

CorvusPay payment on hold: 每个已付款订单都需等待您手动审核。付款仍会记录在订单中。

高级

Logging: 将调试信息写入模块文件夹中的 logs/corvuspay_p_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录；密钥、签名和顾客数据则从不记录。默认：关闭。

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

Delete Data: 开启时，卸载模块会删除模块设置和日志文件。订单、CorvusPay 交易数据和订单状态始终保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Credit/Debit Card (CorvusPay)）并确认。下一页显示 正在跳转到 CorvusPay 进行付款，请稍候...，并将已签名的表单发送到 CorvusPay 付款页面。如果跳转未开始，顾客可点击 Pay via CorvusPay；Back to checkout 将返回结账页面。发送的内容包括购物车总额、货币、简短描述（购物车编号和商店名称）、账单地址信息和电子邮件（用于预填付款页面）。此时尚不存在订单。只要金额、货币、模式和交易类型不变，就会重复使用同一个 CorvusPay 订单号，且 CorvusPay 不会接受针对该订单号的第二次付款。

付款后，CorvusPay 会将顾客带回 Success URL。只有在 CorvusPay 确认后，订单才会被标记为已付款：CorvusPay 订单号必须由本商店颁发，签名必须与发起付款的商店的 Secret Key 相符，且金额和货币必须与购物车一致。随后创建订单，顾客会看到标准订单确认页面，显示 CorvusPay 付款已收到。 对于 Authorize only，页面显示 CorvusPay 付款已授权。商店处理您的订单时将扣除该金额。；对于保留中的订单，则显示 您的付款已收到，商店正在审核。

如果此时无法创建订单（例如另一个请求正在确认同一购物车），顾客会看到 您的付款正在确认 以及 Check again 按钮，订单一旦存在，该按钮就会带您进入订单确认页面。如果无法验证 Success URL 请求，顾客会看到 付款未确认 以及 无法确认此 CorvusPay 付款。如果您的银行卡已被扣款，请联系商店——请勿重复付款。 不会更改任何内容。即使商店处于维护模式，Success URL 仍可正常工作。

如果顾客在 CorvusPay 页面取消，将带着完好的购物车返回结账页面，并显示 CorvusPay 付款已取消，订单未付款。您的购物车仍在——您可以重试或选择其他付款方式。

如果付款无法开始，顾客会留在结账页面，并显示简短消息：CorvusPay 未配置。请选择其他付款方式。、CorvusPay 不接受 … 的付款 或 此订单总额无法通过 CorvusPay 支付（必须大于零，且最多 2 位小数）。请选择其他付款方式。

只有当 CorvusPay 将顾客带回 Success URL 时，订单才会被确认；不存在服务器对服务器的通知。如果顾客在付款后立即关闭浏览器，将不会创建订单。本模块不支持在 PrestaShop 中进行退款、扣款（capture）或撤销（void）（CorvusPay 服务器 API 需要客户端证书），也不支持保存银行卡、订阅、分期付款或商店内的银行卡表单。

订单

订单状态

暂无订单：顾客已被转到 CorvusPay，但尚未带着已确认的付款返回。目前只存在购物车。如果顾客已付款但未返回，请在 CorvusPay Merchant Center 中核实付款，并手动创建订单。

Payment accepted, Delivered 或 CorvusPay payment on hold: Sale 付款已确认。状态遵循 Order Status After Payment。付款以 CorvusPay 交易 ID 记录；如果 CorvusPay 未发送交易 ID，则以 CorvusPay 订单号记录，您可凭此在 Merchant Center 中找到该付款。订单的私密备注会显示 CorvusPay 订单号、批准代码和银行卡类型。

CorvusPay payment on hold, authorized: 已选择 Authorize only。请在 CorvusPay Merchant Center 中扣款（完成）付款，然后将订单设为 Payment accepted。

CorvusPay payment on hold, amount/currency mismatch: 已付金额或货币与购物车不符，例如购物车在另一个标签页中被修改过。如果付款货币与订单货币一致，付款将按实际支付金额记录。在 CorvusPay Merchant Center 中核实付款之前，请勿发货。

CorvusPay payment on hold, payment after cancel: 收到了一笔成功付款，对应的是顾客已取消的付款尝试。请在 CorvusPay Merchant Center 中处理订单或退款。

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

CorvusPay 付款区块

订单页面会显示 CorvusPay payment 区块，包括 CorvusPay 订单号、付款尝试的状态、交易类型（Sale 或 Authorize only）、金额（以及 CorvusPay 报告的实收金额）、批准代码、交易和银行卡类型。测试付款会标记为 Test。

退款：本模块不支持在 PrestaShop 中进行退款、扣款（capture）或撤销（void）。请在 CorvusPay Merchant Center 中操作，并在 PrestaShop 中手动记录结果。

许可证密钥

本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox CorvusPay Gateway 许可证区块位于 Modules > Module Manager > VibeFox CorvusPay Gateway > Configure 页面上设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-corvuspay 一行，以及一个链接“在您的账户中管理许可证和域名”，点击后将打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

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

一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺移除密钥不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥，CorvusPay 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 此付款方式不可用。请选择其他方式。 PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响：从已开始的付款返回的顾客仍会被正常处理。

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

故障排除

CorvusPay 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Store ID 和 Secret Key 是否已填写（测试模式为 Test Store ID 和 Test Secret Key，正式模式为 Live Store ID 和 Live Secret Key），以及购物车货币是否受 CorvusPay 支持。在 Payment > Preferences 中，检查模块是否允许用于购物车货币、顾客所在国家和顾客群组。

付款已完成，但未创建订单：可能是 Success URL 未填写到 CorvusPay Merchant Center，或 PrestaShop 中的 Secret Key 与商店不匹配。请在模块页面的 Log 字段中查找 INVALID signature（错误始终会被记录）。如果顾客在返回前关闭了浏览器，同样不会创建订单；此时请在 Merchant Center 中核实付款，并手动创建订单。

顾客看到“付款未确认”：Success URL 请求被拒绝：缺少必填字段、CorvusPay 订单号不是由本商店颁发的、该商店的 Secret Key 为空，或签名不匹配。不会更改任何内容。日志会显示原因。

顾客长时间看到“您的付款正在确认”：无法创建订单，例如模块已被禁用或购物车已失效。日志会显示原因；请在 Merchant Center 中核实付款。

顾客看到“此订单总额无法通过 CorvusPay 支付”：总额为零，或小数位超过 2 位。

顾客看到“CorvusPay 未配置”或“CorvusPay 不接受 … 的付款”：当前模式的 Store ID 或 Secret Key 缺失，或购物车货币不受支持。

订单处于 CorvusPay payment on hold：请阅读订单的私密备注。原因可能是选择了 Authorize only、已付金额或货币与购物车不符、付款在顾客取消后才到达，或 Order Status After Payment 设为了保留状态。

卸载

进入 Modules > Module Manager，打开 VibeFox CorvusPay Gateway 旁边的菜单，选择 Uninstall。该模块的许可证密钥和许可证状态始终会被移除。如果 Delete Data 已开启，模块设置和日志文件将被删除；如果关闭，则保留所有设置，以便日后重新安装。CorvusPay 交易数据和 CorvusPay payment on hold 订单状态始终保留，因此重新安装后，旧订单的 CorvusPay 区块会重新出现。现有订单会保留其付款备注和交易 ID。

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