VibeFox OpenPay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
HTTPS：您的商店必须使用 HTTPS，因为银行卡表单位于您的结账页面上。
OpenPay 账户：来自墨西哥、哥伦比亚或秘鲁的 OpenPay 账户。您需要其 Merchant ID、私钥（sk_...）和公钥（pk_...）。沙盒和正式环境的控制面板拥有不同的 Merchant ID 和密钥，模块会将它们分开保存。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
银行卡在您的结账页面输入，但由 openpay.js 在浏览器中读取并进行令牌化处理。银行卡字段没有名称，且从不发送到您的服务器。由于银行卡表单位于您的页面上，您的 PCI DSS 范围为 SAQ A-EP；请咨询您的收单机构。
安装
1. 在后台进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox OpenPay Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 选择 Account country，并输入沙盒和正式环境的密钥（参见配置）。
5. 建议：在 OpenPay 控制面板中添加 Webhook URL（参见配置）。
6. 开启 Enable / Disable，然后点击 Save。使用 OpenPay 沙盒测试卡测试付款，然后关闭 Sandbox mode，即可接受真实付款。
安装时，模块会创建两个订单状态：Awaiting OpenPay payment 和 OpenPay payment on hold。PrestaShop 会为您商店的货币、国家和客户群组提供一个新的支付模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox OpenPay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果当前模式的密钥不完整（此时付款方式会在结账时隐藏）、商店的默认货币不被所选账户国家接受，页面会发出警告；启用沙盒模式时，页面会显示 Sandbox mode is enabled — no real charges are made.
保存时会检查密钥。Merchant ID 只能包含字母和数字，私钥必须以 sk_ 开头，公钥必须以 pk_ 开头。无效的值不会被保存：保留之前的值，并显示错误，例如 Sandbox: The private key must start with sk_. 如果已启用付款方式，但当前模式的密钥不完整，您还会看到一条消息，提示网关将在结账时保持隐藏。空的 Title 会被拒绝，并提示 Enter a title for the payment method.
OpenPay
Enable / Disable：Enable OpenPay card payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit or debit card (OpenPay)。必填。
Description：结账时银行卡表单上方显示的文字。默认：Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure)。
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：沙盒控制面板 Settings (Configuración) 中 API 密钥部分的 Merchant ID。
Sandbox Private Key：沙盒私钥。以 sk_ 开头。仅在服务器端使用；切勿分享。
Sandbox Public Key：沙盒公钥。以 pk_ 开头。openpay.js 在浏览器中使用它来对银行卡进行令牌化处理。
Live Merchant ID：正式环境控制面板 Settings (Configuración) 中 API 密钥部分的 Merchant ID。
Live Private Key：正式环境私钥（sk_...）。
Live Public Key：正式环境公钥（pk_...）。
已保存的私钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在您需要更改时才输入新值。
Clear saved secrets：勾选某个私钥并点击 Save 即可将其删除。字段为空时将保留已保存的值。
Webhook
Webhook 不是必需的，但建议配置。当顾客没有从 3D Secure 页面返回时（例如关闭浏览器之后），它可以确认付款。在 OpenPay 控制面板中进入 Settings > Webhooks，并添加本部分 Webhook URL 中显示的 URL。启用友好 URL 时，它的形式为 https://your-shop/module/wcp_openpay_gateway/webhook，前面可能带有语言代码，例如 /en/。请按照设置中显示的内容原样复制。请在您使用的每种模式（沙盒和正式环境）的控制面板中添加 Webhook。
添加 Webhook 时，OpenPay 会向此 URL 发送一个验证码。该验证码会显示在本部分中，并附有到达日期，以便您在 OpenPay 控制面板中确认 Webhook。
请选择以下事件（本部分也列出了这些事件）：
OpenPay 不对 Webhook 进行签名，因此模块从不信任通知本身。它只用通知来查找扣款，然后使用付款所在模式和账户国家的私钥，从 OpenPay API 读取扣款信息。对于本商店未创建的扣款的通知会被忽略。即使商店处于维护模式，Webhook 也会正常工作，并且不受商店国家限制的阻止。
高级
Debug log：将付款步骤记录到模块文件夹中的 logs/wc_opy_debug.log.php。该文件无法通过网页打开。即使关闭，错误和警告仍会被记录。密钥、银行卡数据和顾客详细信息从不记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除网关设置、已保存的 Webhook 验证码和日志。订单的 OpenPay 扣款记录属于付款历史，始终保留，因此重新安装后仍可对订单退款。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Credit or debit card (OpenPay)），并填写 Cardholder name、Card number、Expiry (MM/YY) 和 Card code (CVV)。在沙盒模式下，表单会显示 SANDBOX MODE — Test environment. No real charges will be made. 顾客确认后，openpay.js 会在浏览器中将银行卡转换为一次性令牌，反欺诈库会添加设备会话 ID。只有这两个值和购物车编号会发送到您的商店。如果表单未填写完整，表单下方会显示 Please fill in all card fields.
随后，模块会以购物车货币、按购物车总额创建带 3D Secure 验证的扣款，并将顾客引导至其银行的 3D Secure 页面（由 OpenPay 提供）。每次尝试都会获得自己的 OpenPay 订单参考号。扣款描述为 Cart #、购物车编号以及您的商店名称。顾客的姓名、电子邮件和电话会传递给 OpenPay；不会在 OpenPay 中创建客户账户。此时尚未生成订单。
顾客返回时，模块会从 OpenPay API 读取扣款信息。只有在 OpenPay 确认后，订单才会被标记为已付款：扣款必须属于此购物车、已完成，并且与购物车总额和货币完全一致。随后订单会被创建，顾客会看到订单确认页面，显示 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.，然后可以再次付款。购物车会被保留。在发起新的尝试之前，模块会检查该购物车之前的扣款：如果实际已付款，则直接根据它创建订单，不会再次扣款；如果仍在处理中，则以 Awaiting OpenPay payment 状态创建订单；如果无法确认其状态，则不会发起新的扣款，顾客会看到 We could not confirm the status of your previous payment attempt. Please try again in a few minutes. 已有订单的购物车绝不会再次扣款。
被拒的银行卡会收到清晰的提示，例如 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 的技术性错误绝不会显示给顾客，而是会记录到日志中。
如果购物车中的优惠券在付款与确认之间失效，它会从订单中移除。随后订单会进入 OpenPay payment on hold 状态并附带备注，因为顾客是以折扣价付款的。
当付款方式被禁用、当前模式的密钥不完整，或购物车货币不被账户国家接受时，结账页面会隐藏该付款方式。
本模块仅接受银行卡付款，并立即捕获。不支持保存的银行卡、订阅、免息分期或分期付款、信用卡积分付款、现金、SPEI、PSE 或 CoDi 付款，也不支持单独的授权与捕获。
订单与退款
订单状态
尚无订单：顾客位于 3D Secure 页面，尚未完成付款，或银行卡被拒。仅存在购物车。
Payment accepted：付款已确认。付款将以 OpenPay 扣款 ID 作为交易 ID 记录，备注中显示扣款 ID 以及模式（正式或沙盒）。
Awaiting OpenPay payment：OpenPay 报告扣款仍在处理中（尚未捕获）。扣款完成后，订单会转为 Payment accepted；如果失败，则转为 Payment error。
OpenPay payment on hold：OpenPay 报告已完成的扣款金额或货币与购物车不一致（订单不会被标记为已付款，备注中显示差额），优惠券已被移除，或某个已取消或已退款的订单收到了付款（付款会被记录）。请检查订单并处理，或在 OpenPay 控制面板中退还该付款。
Payment error：处理中的扣款失败、被取消或已过期。
Refunded：扣款已通过模块全额退款。
如果已付款的订单又收到一笔已完成的扣款，订单不会被更改。以 WARNING 开头的备注会提醒您在 OpenPay 控制面板中退还重复的扣款。
OpenPay 付款区块
订单页面会显示一个 OpenPay payment 区块，其中包括扣款 ID、扣款状态、环境和账户国家、扣款金额与订单总额、已退款金额、沙盒付款的 Sandbox 标识、退款记录，以及订单的 OpenPay notes。
退款
适用于墨西哥和秘鲁的账户：在 OpenPay payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via OpenPay。请确认提示 Refund this amount through OpenPay? This cannot be undone. 支持全额和部分退款，金额上限为 OpenPay 扣款的金额。您需要具有编辑订单的权限。退款会使用扣款所在模式和账户国家的密钥发送，因此必须设置该模式的密钥：只要您仍可能需要退还沙盒订单，就请保留沙盒密钥。如果 OpenPay 不接受退款，区块会显示错误，例如 OpenPay refund failed: ...，并且不会记录任何退款。退款成功后，会将 OpenPay 退款 ID 添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。只有在 OpenPay 确认付款后才能退款；因金额不符而处于 OpenPay payment on hold 状态的订单无法通过模块退款。
与 OpenPay 官方插件一样，OpenPay Colombia 不支持通过 API 进行银行卡退款。对于哥伦比亚的扣款，该区块不提供退款表单；请在 OpenPay 控制面板中退还扣款。
模块不会生成退款凭证。PrestaShop 订单页面上的标准退款按钮不会通过 OpenPay 退款。
在 OpenPay 控制面板中进行的退款和拒付会通过 Webhook 传回，并且只会添加到备注中一次。订单状态和退款凭证不会自动更改，如有需要，请手动更新。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox OpenPay Gateway 是 Modules > Module Manager > VibeFox OpenPay Gateway > Configure 页面上的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-payment-openpay 一行，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，在多店铺配置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 OpenPay。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已经开始的付款仍会被确认，退款也仍可进行。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 OpenPay：请检查许可证是否有效，Enable / Disable 是否已开启，以及当前模式是否具备全部三个密钥：沙盒模式需要沙盒密钥，正式模式需要正式密钥。请检查购物车货币是否被 Account country 接受（墨西哥：MXN、USD；哥伦比亚：COP、USD；秘鲁：PEN、USD）。设置页面会在每种情况下显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车货币、顾客所在国家和顾客群组。
付款已完成，但未创建订单：顾客没有从 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 以查看原因。
顾客看到 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：沙盒模式关闭时使用了沙盒测试卡。
付款后订单处于 OpenPay payment on hold：请阅读区块中的 OpenPay notes（参见订单状态），然后处理订单或退还付款。
退款因模式相关信息而失败：订单是在沙盒或正式模式下付款的，但该模式的密钥未设置。请输入这些密钥后重试。
退款提示 The order is being updated right now 而失败：Webhook 或其他请求正在同一时刻更新订单。请稍后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox OpenPay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置、已保存的 Webhook 验证码和日志都会被删除。如果已关闭，所有设置都会保留，以便以后重新安装。OpenPay 扣款和退款记录，以及订单状态 Awaiting OpenPay payment 和 OpenPay payment on hold，始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
OpenPay 是其各自所有者的商标。本模块与 OpenPay 没有关联，也未获得 OpenPay 的认可。