VibeFox CorvusPay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：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 必须在那里填写（参见 Configuration）。

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

安装

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

OpenCart 3

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

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

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

4. 输入 CorvusPay 测试店铺的 Store ID 和 Secret Key（如果要接收正式付款，还需输入正式店铺的信息）。将设置页面上显示的 Success URL 和 Cancel URL 复制到 CorvusPay Merchant Center 中，测试店铺和正式店铺都要填写。

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

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥、CorvusPay 店铺信息和 Merchant Center 网址。设置页面及其字段在两个版本中相同。只有 Success URL 和 Cancel URL 不同（参见 Success 和 Cancel URL）。

新安装默认关闭付款方式，并开启测试模式。

Configuration

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit。设置分区列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，测试模式开启时页面会显示 Test mode is on. Payments go to the CorvusPay test environment — no real money is taken.；如果网关已启用，但当前模式的 Store ID 或 Secret Key 为空（此时结账时会隐藏该付款方式，直到填写完成），或者店铺的默认货币不受 CorvusPay 支持，页面也会向您发出警告。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能超过 128 个字符，Sort Order 必须是整数，Minimum Total 必须是非负数，所选的地理区域和订单状态必须存在；否则不会保存任何内容，页面会列出错误。

CorvusPay

Enable/Disable：Enable CorvusPay Gateway. 用于开启或关闭付款方式。Default：off。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。Default：Credit/Debit Card (CorvusPay)。最多 128 个字符；如果留空，则显示默认名称。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。Default：Pay securely with your credit or debit card via CorvusPay。在测试模式下会附加 (Test mode — no real payment is taken.)

Sort Order：CorvusPay 在结账时的付款方式中的排列位置。可留空或输入整数。

Geo Zone：仅为所选地理区域内的付款地址提供 CorvusPay。Default：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Minimum Total：订单必须达到的金额（以店铺默认货币计算），达到后才会提供 CorvusPay。留空则没有最低金额限制。

店铺凭据

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

Test Mode：使用 CorvusPay 测试环境（wallet.test.corvuspay.com）以及测试用的 Store ID 和 Secret Key。Default：on。关闭后将在 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 签名。

Store ID 只能包含数字。如果您输入了其他内容，页面会显示 … must contain digits only — the previous value was kept.，但其他字段仍会保存。已保存的 Secret Key 不会再次显示：该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选该字段下方的 Clear the saved value on save，然后点击 Save。付款始终使用发起该付款的店铺的 Secret Key 进行验证，因此在测试付款仍可能返回期间，请保持测试密钥已填写。

Success 和 Cancel URL

将 Merchant Center URLs 中显示的两个地址复制到 CorvusPay Merchant Center，测试店铺和正式店铺都要填写。付款完成后，CorvusPay 会将顾客带回这两个地址。它们是根据您 OpenCart 安装的店铺前台地址生成的；请完全按照页面显示的内容复制。

付款

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

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

Order Status After Payment：Sale 付款成功后的订单状态。这些选项对应 Order statuses 部分中所选的 OpenCart 状态。

订单状态

OpenCart 在 Confirm Order 步骤创建订单，此时没有状态（缺失订单）。以下是网关设置的 OpenCart 状态；每个字段都列出您的 OpenCart 订单状态。OpenCart 没有 On hold 状态，因此审核状态用于 Authorize only、金额或币种不符以及取消后的付款；订单备注会说明原因。

Processing status：当 Order Status After Payment 为 Processing 时使用。Default：Processing。

Completed status：当 Order Status After Payment 为 Completed 时使用。Default：Complete。

On hold (review) status：Authorize only、金额或币种不符、取消后的付款，或将 Order Status After Payment 设为 On hold。Default：Pending。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

高级

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

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

Delete Data：开启时，卸载扩展会删除网关设置和日志文件。订单和 CorvusPay 交易数据始终会被保留。Default：off。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。Secret Key 不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit/Debit Card (CorvusPay)）。在 Confirm Order 步骤中，顾客会看到您的说明；OpenCart 在此步骤创建订单，仍然没有状态。当顾客点击 Confirm Order 时，页面会显示 Redirecting to CorvusPay for payment. Please wait...，并将已签名的表单发送到 CorvusPay 付款页面。如果未能自动跳转，顾客可点击 Pay via CorvusPay。发送的内容包括：以订单货币计算的订单总额、简短说明（Order、订单号和店铺名称），以及顾客的地址信息和电子邮件（用于预先填充付款页面）。只要金额、货币、模式和交易类型不变，就会重复使用同一个 CorvusPay 订单号，并且 CorvusPay 不会为它接受第二笔付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。如果店铺不要求付款地址（OpenCart 4 默认设置），则持卡人信息取自顾客姓名和收货地址。

付款后，CorvusPay 会将顾客带回 Success URL。只有在 CorvusPay 确认之后，订单才会被标记为已付款：CorvusPay 订单号必须是由本店铺签发的，签名必须与发起付款的店铺的 Secret Key 相符，金额和币种也必须与订单相符。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，并显示 Your CorvusPay payment has been received. 对于 Authorize only，页面会显示 Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order.；对于处于审核状态的订单，页面会显示 Your payment was received and is being reviewed by the shop.

如果此时无法应用付款（例如，另一个请求正在确认同一订单），顾客会看到 Your payment is being confirmed 以及一个 Check again 按钮；订单一旦获得状态，该按钮就会将顾客带到成功页面。如果无法验证 Success URL 的请求，顾客会看到 Payment not confirmed 以及 We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. 不会做任何更改。即使店铺处于维护模式，Success URL 仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会为 Success 和 Cancel URL 添加一个启动操作。在 OpenCart 4 中，CorvusPay 把顾客送回时浏览器不会发送店铺会话，因此扩展会先显示一个短暂页面，从您的店铺再次打开同一地址：顾客会保留购物车和登录状态。

如果顾客在 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. 在 OpenCart 4 中，此消息显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 为结账保留一个订单并对其进行更新，新的尝试会获得新的 CorvusPay 订单号；如果同一购物车的另一个订单已付款，顾客会被带到成功页面，而不会再次付款。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单在未付款的情况下已被关闭（例如您取消了它），Confirm Order 或从 CorvusPay 的返回会将顾客带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.。如果订单已有状态，且此后购物车发生了变化（其他商品或数量），则显示 Your previous order is already placed. The cart has changed since then: please confirm the new order to pay for it.。两种情况下，下一次 Confirm Order 都会为购物车支付一个新订单。

如果付款无法启动，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息：CorvusPay is not configured. Please choose another payment method.、CorvusPay does not accept payments in … 或 This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

只有当 CorvusPay 将顾客带回 Success URL 时，订单才会被确认；没有服务器对服务器的通知。如果顾客在付款后立即关闭浏览器，订单会保持无状态。该扩展不支持从 OpenCart 进行退款、扣款或撤销（CorvusPay 的服务器 API 需要客户端证书），也不支持保存的银行卡、订阅、分期付款或店铺内的银行卡表单。

订单

订单状态

无状态（缺失订单）：顾客已被带到 CorvusPay，但没有带着已确认的付款返回，或者取消了付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时，才会显示此类订单。如果顾客已付款但没有返回，请在 CorvusPay Merchant Center 中检查付款，并手动设置订单状态。

Processing、Completed 或审核状态：Sale 付款已确认。状态遵循 Order Status After Payment。备注中会显示 CorvusPay 订单号、授权码和银行卡类型。

审核状态，已授权：已选择 Authorize only。请在 CorvusPay Merchant Center 中扣款，然后更改订单状态。

审核状态，金额或币种不符：已付金额或币种与订单不符。请先在 CorvusPay Merchant Center 中核实付款，再发货。

审核状态，取消后付款：顾客已取消的付款尝试收到了一笔成功付款。请在 CorvusPay Merchant Center 中处理订单，或退还该笔付款。

如果已付款的订单又收到另一笔成功付款，订单不会被更改。备注会请您检查 CorvusPay Merchant Center，并在需要时退还重复付款。如果在一个订单已付款的情况下，同一购物车的另一个订单收到了付款，则该订单保持无状态，并将备注添加到已付款的订单中。

备注是订单 History 中顾客看不到的记录。

VibeFox CorvusPay Gateway 选项卡

在 Sales > Orders 中打开一个使用 CorvusPay 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox CorvusPay Gateway 选项卡会显示 CorvusPay order number、付款尝试的 Status、Transaction type、Amount（如果 CorvusPay 报告了收到的金额，也会显示）、Approval code、Transaction、Card 类型以及 CorvusPay notes。测试付款会标记为 Test。该选项卡为只读，显示给有权访问该扩展的用户。

退款：不支持从 OpenCart 进行退款、扣款和撤销。请在 CorvusPay Merchant Center 中进行这些操作，并在 OpenCart 中手动记录结果。Sales > Returns 中的商品退货不会通过 CorvusPay 退还款项。

许可证密钥

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

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

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

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

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

故障排除

CorvusPay 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的 Store ID 和 Secret Key 是否已填写（测试模式为 Test Store ID 和 Test Secret Key，正式模式为 Live Store ID 和 Live Secret Key），以及结账货币是否受 CorvusPay 支持。另外，还请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到 Minimum Total。

付款已完成，但订单仍然没有状态：很可能是 Success URL 没有填写到 CorvusPay Merchant Center 中，或者 OpenCart 中的 Secret Key 与店铺不匹配。请在扩展页面的 Log 字段中查找 INVALID signature（错误始终会被记录）。如果顾客在返回前关闭了浏览器，订单也会保持无状态；这种情况下，请在 Merchant Center 中检查付款，并手动设置订单状态。

顾客看到 Payment not confirmed：对 Success URL 的请求被拒绝：缺少必填字段、CorvusPay 订单号不是由本店铺签发的、该店铺的 Secret Key 为空，或签名不匹配。没有任何更改。日志会显示原因。

顾客长时间看到 Your payment is being confirmed：无法设置订单状态。日志会显示原因；请在 Merchant Center 中检查付款。

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

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

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

订单处于审核状态：请阅读 VibeFox CorvusPay Gateway 选项卡中的备注。已选择 Authorize only，已付金额或币种与订单不符，付款是在顾客取消之后到达的，或者 Order Status After Payment 被设为 On hold。

对开发者：在表单签名之前，扩展会触发 OpenCart 事件 corvuspay_p_form_params，其中包含表单字段和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox CorvusPay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Minimum Total，以及 Order statuses 部分中的状态（重新安装时恢复为默认值）。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件和使 CorvusPay 能在维护模式下通过的启动操作）。如果 Delete Data 已开启，则其余网关设置（标题、说明、Store ID、Secret Key、测试模式、付款设置、日志记录）和日志文件都会被删除。如果已关闭，它们会被保留，以便日后重新安装。CorvusPay 交易数据始终会被保留，因此旧订单的 CorvusPay 选项卡在重新安装后会重新出现。现有订单会保留其付款备注。

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

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