VibeFox OpenPay for OpenCart — 帮助

要求

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

PHP: 8.0 或更高版本。

HTTPS: 您的商店必须使用 HTTPS，因为银行卡表单位于结账页面。

OpenPay account: 来自墨西哥、哥伦比亚或秘鲁的 OpenPay 账户。您需要其 Merchant ID、私钥（sk_...）和公钥（pk_...）。沙盒和正式环境的控制面板使用不同的 Merchant ID 和密钥，扩展会将它们分开保存。

Currency: 客户必须使用您账户所在国家/地区接受的货币付款：墨西哥 — MXN 或 USD，哥伦比亚 — COP 或 USD，秘鲁 — PEN 或 USD。对于其他货币，结账时不会显示该付款方式。

VibeFox license key: 在 vibefox.net 购买。一个密钥只能用于一个域名。

银行卡信息在您的结账页面输入，但由 openpay.js 在浏览器中读取并进行令牌化处理。银行卡字段没有名称，且从不会发送到您的服务器。由于银行卡表单位于您的页面上，您的 PCI DSS 范围为 SAQ A-EP；请咨询您的收单机构。

安装

下载文件是一个压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_openpay_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_openpay_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

4. 选择 Account country，并输入沙盒和正式环境的密钥（参见配置）。

5. 推荐：在 OpenPay 控制面板中添加 Webhook URL（参见配置）。

6. 开启 Enable / Disable 并点击 Save。使用 OpenPay 沙盒测试卡测试一笔付款，然后关闭 Sandbox mode 以接受真实付款。在您可能仍需要退款沙盒订单之前，请保留沙盒密钥。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_openpay_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。

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

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

4. 请按照 OpenCart 3 步骤 3 至 6 输入许可证密钥、OpenPay 密钥和 Webhook。两个版本的设置页面及其字段完全相同，只有 Webhook URL 不同（参见 Webhook）。

新安装时，付款方式默认关闭，沙盒模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox OpenPay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮可保存整个页面。在设置上方，当当前模式的密钥不完整时（此时付款方式会在结账页面隐藏）、当商店的默认货币不被所选账户国家/地区接受时，页面会提示您；启用沙盒模式期间，页面会显示 Sandbox mode is enabled — no real charges are made. 如果您没有修改扩展的权限，页面只显示设置，无法保存。

保存时会检查密钥。Merchant ID 只能包含字母和数字，私钥必须以 sk_ 开头，公钥必须以 pk_ 开头。无效的值不会被保存：保留之前的值，并显示错误，例如 Sandbox: The private key must start with sk_. 如果 Sort Order 不是整数（Sort Order must be a whole number — the previous value was kept.），或 Total 不是大于或等于 0 的数字，也会出现同样的情况。其他字段仍会保存。如果付款方式已启用，但当前模式的密钥不完整，您还会看到一条消息，提示网关将在结账页面保持隐藏。Title 为空或超过 128 个字符会被拒绝，并显示 Enter a title for the payment method (1 to 128 characters).，此时不会保存任何内容。

OpenPay

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

Title: 客户在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Credit or debit card (OpenPay)。必填，最多 128 个字符。

Description: 在 Confirm Order 步骤中银行卡表单上方显示的文字。默认：Pay securely with your credit or debit card. 您的银行可能会要求您确认付款（3D Secure）。

Sort Order: OpenPay 在结账页面付款方式中的排列位置。留空或输入整数（允许负数）。

Geo Zone: 仅为所选地理区域内的付款地址提供 OpenPay。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，如果商店不要求付款地址，则使用收货地址。

Total: 订单必须达到的结账金额（以商店默认货币计）才会提供 OpenPay。留空则对任意金额都提供 OpenPay。

OpenPay 账户

Merchant ID、私钥（sk_）和公钥（pk_）位于您的 OpenPay 控制面板的 Settings (Configuración) 下。该部分包含墨西哥、哥伦比亚和秘鲁的沙盒及正式环境控制面板链接。

Account country: 您的 OpenPay 账户所在国家/地区。它决定使用的 OpenPay API、该国家/地区的 openpay.js 库以及可接受的货币。默认：Mexico。

Sandbox mode: 使用 OpenPay 沙盒（测试密钥，不产生真实扣款），并将密钥和 API 都切换到沙盒。开启期间，结账页面会显示 SANDBOX MODE 标识。默认：开启。关闭以接受真实付款。

Sandbox Merchant ID: 沙盒控制面板中的 Merchant ID，位于 Settings (Configuración) 的 API 密钥部分。

Sandbox Private Key: 沙盒私钥。以 sk_ 开头。仅在服务器端使用；切勿分享。

Sandbox Public Key: 沙盒公钥。以 pk_ 开头。openpay.js 在浏览器中使用它对银行卡进行令牌化处理。

Live Merchant ID: 正式环境控制面板中的 Merchant ID，位于 Settings (Configuración) 的 API 密钥部分。

Live Private Key: 正式环境私钥（sk_...）。

Live Public Key: 正式环境公钥（pk_...）。

已保存的私钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的私钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。

Webhook

Webhook 不是必需的，但建议配置。当客户没有从 3D Secure 页面返回时（例如关闭浏览器后），它可以确认付款。在 OpenPay 控制面板中进入 Settings > Webhooks，并添加本节 Webhook URL 中显示的 URL。该 URL 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_openpay_gateway/webhook，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_openpay_gateway/payment/wcp_openpay_gateway.webhook。该 URL 由您的 OpenCart 安装的前台地址生成。请完全按照设置中显示的内容复制。请在您使用的每个模式（沙盒和正式环境）的控制面板中分别添加 Webhook。

添加 Webhook 后，OpenPay 会向该 URL 发送一个验证码。验证码会显示在本节中，并附有到达日期，以便您在 OpenPay 控制面板中确认 Webhook。在此之前，本节显示 No verification code received yet.

该扩展处理以下事件：

OpenPay 不对 Webhook 签名，因此扩展从不信任通知本身。它只用通知来查找扣款，然后使用付款所在模式和账户国家/地区的私钥，通过 OpenPay API 读取扣款信息。对于本商店未创建的扣款的通知会被忽略。即使商店处于维护模式，Webhook 也能正常工作：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动操作，使 Webhook 以及客户从 3D Secure 返回的请求得以通过。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单）。只有在 OpenPay 确认扣款后，订单才会获得状态。银行卡被拒绝或 3D Secure 验证失败会使订单保持无状态，备注会说明原因，客户可以重新付款。下方每个字段都列出了您的 OpenCart 订单状态；您可以在 System > Localisation > Order Statuses 中创建自己的状态。

Order Status After Payment: OpenPay 已确认扣款，且其金额和货币与订单一致。默认：Processing。

Awaiting OpenPay Payment: 扣款正在进行中（尚未捕获）；Webhook 随后会完成或使其失败。默认：Pending。

OpenPay Payment On Hold: OpenPay 扣除的金额或货币与订单不同，或者订单已取消后扣款才完成。默认：Pending。

Payment Error Status: 等待 OpenPay 或处于保留状态的订单的扣款失败、被取消或已过期。默认：Failed。

Refunded Status: 从订单页面全额退款后扣款的状态。部分退款仅添加备注。默认：Refunded。

高级

Debug log: 将付款步骤记录到 OpenCart 日志文件夹（storage/logs）中的 wc_opy_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 wc_opy_debug.old.log.php。即使关闭该选项，错误和警告仍会被记录。密钥、银行卡数据和客户信息从不记录。默认：关闭。

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

Delete data on uninstall: 开启后，卸载扩展时会删除网关设置、已保存的 Webhook 验证码和日志。订单的 OpenPay 扣款记录属于付款历史，始终会被保留，因此重新安装后订单仍可退款。默认：关闭。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。私钥不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的私钥会被保留。

结账

在 Payment Method 步骤中，客户选择付款方式（默认为 Credit or debit card (OpenPay)）。在 Confirm Order 步骤中，客户会看到您的描述和银行卡表单：Cardholder name、Card number、Expiry (MM/YY) 和 Card code (CVV)。在沙盒模式下，表单会显示 SANDBOX MODE — Test environment. No real charges will be made. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，客户通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式；银行卡表单位于结账页面底部的确认区域，在 Confirm Order 上方。当客户点击 Confirm Order 时，openpay.js 会在浏览器中将银行卡转换为一次性令牌，反欺诈库会添加设备会话 ID。只有这两个值会发送到您的商店。如果表单未填写完整，表单下方会显示 Please fill in all card fields.

随后，扩展会以订单货币创建包含 3D Secure 的扣款（金额为订单总额），并将客户带到其银行的 3D Secure 页面（由 OpenPay 提供）。每次尝试都会获得独立的 OpenPay 订单参考号。扣款描述为 Order #、订单号和您的商店名称。付款地址中的客户姓名、电子邮件和电话会传递给 OpenPay；不会在 OpenPay 中创建客户账户。

客户返回后，扩展会通过 OpenPay API 读取扣款信息。只有在 OpenPay 确认后，订单才会被标记为已付款：扣款必须属于该订单、已完成，并且与订单总额和货币完全一致。随后，订单以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，客户会看到 OpenCart 订单成功页面，并显示 Your card payment has been received. 如果 OpenPay 报告扣款仍在进行中，订单会获得 Awaiting OpenPay Payment 状态，页面会显示 We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. 如果结果尚不确定，Payment confirmation 页面会显示相同的文字，并带有 Check again 按钮和 Back to checkout 按钮；Webhook 到达后会立即设置订单状态。如果进行中的扣款之后失败，成功页面会显示 Your OpenPay card payment was not completed. Please contact us about this order.

如果银行卡被拒绝或 3D Secure 失败，订单保持无状态，添加备注，客户会返回结账页面，并显示 The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. 购物车会保留。在 OpenCart 4 中，此提示显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 则会保留结账中的一个订单并进行更新，因此客户会以新的尝试为同一订单再次付款。在进行新的尝试之前，扩展会检查购物车之前的扣款：如果实际已付款，该订单会获得状态，而不会再次扣款；如果仍在处理中，客户会看到 A previous payment for this order is still being processed. Please do not pay again — the order will be updated automatically.；如果无法检查其状态，则不会进行新的扣款，客户会看到 We could not confirm the status of your previous payment attempt. Please try again in a few minutes. 已支付的购物车永远不会被再次扣款。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭（例如其等待付款后的扣款失败，或您取消或退款了该订单），客户会被带回结账页面，并看到 This order can no longer be paid. Please reload the checkout page and confirm the order again.，下一次点击 Confirm Order 将为一个新订单付款。如果该订单已有状态，而购物车中现在包含其他商品或数量，客户同样会被带回结账页面，新购物车会获得新的订单。

被拒绝的银行卡会收到明确的提示，例如 The card has insufficient funds. Please use another card.、The card has expired. Please use another card. 或 The security code (CVV) is not valid. Please check it and try again. OpenPay 的技术错误从不向客户显示；它们会进入日志和订单备注。

当付款方式被禁用、当前模式的密钥不完整或客户使用账户所在国家/地区不接受的货币付款时，结账页面会隐藏该付款方式。

该扩展仅接受银行卡付款，并立即扣款。它不支持保存的银行卡、订阅、免息分期（MSI）或分期付款、使用银行卡积分付款、现金、SPEI、PSE 或 CoDi 付款，也不支持单独的授权和捕获。

订单与退款

订单状态

No status (missing order): 客户正处于 3D Secure 页面，尚未完成付款，或银行卡被拒绝。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders，才会显示此类订单。

在 OpenCart 4 中，结账中未付款的订单可能会获得 Voided 状态，该状态由 OpenCart 4 在客户返回 Confirm Order 步骤时设置。扩展会将此类订单视为无状态订单，之后的付款仍会确认该订单。

Order Status After Payment (default Processing): 付款已确认。备注会显示 OpenPay 扣款 ID 以及模式（正式环境或沙盒）。

Awaiting OpenPay Payment (default Pending): OpenPay 报告扣款仍在进行中（尚未捕获）。扣款完成后，订单会转为 Order Status After Payment；若扣款失败，则转为 Payment Error Status。

OpenPay Payment On Hold (default Pending): OpenPay 报告已完成的扣款金额或货币与订单不同（订单不会被标记为已付款，备注会显示差额），或者在订单已取消或已退款后收到了付款。请检查订单，然后处理订单或为付款退款。

Payment Error Status (default Failed): 进行中的扣款失败、被取消或已过期。

Refunded Status (default Refunded): 扣款已通过扩展全额退款。

如果对已付款的订单或购物车收到第二笔已完成的扣款，订单不会被更改。已付款订单上以 OpenPay WARNING 开头的备注会提示您在 OpenPay 控制面板中为重复扣款退款。

备注是订单 History 中的条目，客户看不到。

VibeFox OpenPay Gateway 标签页

在 Sales > Orders 中打开一个使用 OpenPay 付款的订单。在订单页面底部，紧挨 History 和 Additional 的位置，VibeFox OpenPay Gateway 标签页会显示扣款 ID、扣款状态、环境和账户国家/地区（沙盒付款会带有 Sandbox 标签）、Charged / order 金额、已退款金额、退款表单、退款历史以及订单的 OpenPay notes。该标签页显示给有权访问扩展的用户。

退款

对于墨西哥和秘鲁的账户：在标签页中输入 Amount（未退款金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via OpenPay。确认提示 Refund this amount through OpenPay? This cannot be undone. 支持全额和部分退款，金额不得超过 OpenPay 所扣的金额。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款使用扣款所在模式和账户国家/地区的密钥发送，因此必须已设置该模式的密钥。如果 OpenPay 不接受退款，标签页会显示错误，例如 OpenPay refund failed: ...，并且不会记录任何退款。成功的退款会连同 OpenPay 退款 ID 添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，且不通知客户，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。OpenPay 确认付款后才可以退款；因金额不符而保留的订单无法通过扩展退款。

与官方 OpenPay 集成一样，OpenPay 哥伦比亚不通过 API 支持银行卡退款。对于哥伦比亚的扣款，标签页不提供退款表单，并会说明原因；请在 OpenPay 控制面板中为该扣款退款。

Sales > Returns 中的商品退货不会通过 OpenPay 退还款项。

在 OpenPay 控制面板中进行的退款和拒付会通过 Webhook 送达，并且只会添加到备注中一次。订单状态不会自动更改。如有需要，请手动更新。

许可证密钥

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

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

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

没有有效密钥时，结账页面不会向客户显示 OpenPay。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在商店中看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览功能：商店无法看到后台的管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也可正常进行。

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

故障排除

OpenPay 未出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，以及当前模式是否具有全部三个密钥：沙盒模式下使用沙盒密钥，正式模式下使用正式密钥。检查客户是否使用 Account country 接受的货币付款（墨西哥：MXN、USD；哥伦比亚：COP、USD；秘鲁：PEN、USD）。在每种情况下，设置页面都会显示警告。另请检查付款地址是否在所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已成功，但订单仍无状态：客户没有从 3D Secure 页面返回，且 Webhook 未正常工作。请检查您所使用模式的 OpenPay 控制面板中是否已添加 Webhook URL，并且与设置中显示的完全一致，同时包含上面列出的事件。检查付款所在模式的密钥是否已填写：没有密钥时，Webhook 会返回 not configured，OpenPay 稍后会重试。当客户返回商店，或尝试再次支付同一购物车时，订单也会获得状态。

Webhook 返回 ignored (unknown order)：该扣款并非由本商店创建，例如同一 OpenPay 账户上其他商店的扣款。不会进行任何更改。

Webhook 返回 verification failed：无法访问 OpenPay API 以读取扣款信息。OpenPay 会重试该 Webhook。

Webhook 返回 busy：购物车正被另一请求同时更新，或无法设置订单状态。OpenPay 会重试该 Webhook。开启 Debug log 以查看原因。

Webhook URL 在浏览器中显示 invalid body：这是正常现象。该 URL 只接受来自 OpenPay 的通知。

客户看到 The secure card form could not be loaded：OpenPay 的 openpay.js 或反欺诈库未能在浏览器中加载，或无法创建设备会话 ID。请让客户刷新页面后重试。

客户看到 The payment could not be processed right now：OpenPay 拒绝了请求或未作响应。原因记录在日志和订单备注中。Merchant ID 或私钥错误是常见原因。如果 OpenPay 未作响应，请在客户再次付款前，在 OpenPay 控制面板中检查该扣款。

客户看到 This test card cannot be used for real payments：沙盒模式关闭时使用了沙盒测试卡。

客户看到 Billing email is required for OpenPay：订单没有有效的电子邮件地址。

订单在付款后处于 OpenPay Payment On Hold 状态：请阅读标签页中的 OpenPay notes（参见订单状态），然后处理订单或为付款退款。

退款因与模式有关的消息而失败：订单是在沙盒或正式模式下付款的，但该模式的密钥尚未设置。请输入密钥后重试。

退款因 The order is being updated right now 而失败：Webhook 或其他请求正在同时更新订单。请稍后重试。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox OpenPay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，启动操作用于在维护模式下放行 Webhook 以及 3D Secure 返回）。如果开启了 Delete data on uninstall，则其他网关设置（标题、描述、账户国家/地区、沙盒模式、密钥、日志记录）、已保存的 Webhook 验证码和日志都会被删除。如果关闭，则会保留这些内容，以便之后重新安装时使用。OpenPay 的扣款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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