VibeFox OpenPay for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。
PHP：8.0 或更高版本。
HTTPS：您的站点必须使用 HTTPS，因为银行卡表单位于您的结账页面上。
OpenPay 账户：墨西哥、哥伦比亚或秘鲁的 OpenPay 账户。您需要其 Merchant ID、私钥（sk_...）和公钥（pk_...）。沙盒和正式环境的控制面板使用不同的 Merchant ID 和密钥，插件会将它们分开保存。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
银行卡信息在您的结账页面输入，但由 openpay.js 在浏览器中读取并进行令牌化处理。银行卡字段没有名称，且绝不会发送到您的服务器。由于银行卡表单位于您的页面上，您的 PCI DSS 范围为 SAQ A-EP；请咨询您的收单机构。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_openpay_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > OpenPay > Manage，或在插件列表页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择 Account country，并输入沙盒和正式环境的密钥（参见配置）。
6. 建议：在 OpenPay 控制面板中添加 Webhook URL（参见配置）。
7. 启用 Enable / Disable 并保存。使用 OpenPay 沙盒测试卡测试一笔付款，然后取消勾选 Sandbox mode 以接收真实付款。
配置
所有设置都在同一个页面：WooCommerce > Settings > Payments > OpenPay。页面在字段上方会提示：当前模式的密钥不完整时（此时该付款方式会在结账时隐藏）、店铺货币不被所选账户国家接受时，并且在沙盒模式开启时显示 Sandbox mode is enabled — no real charges are made. 在付款方式列表中，OpenPay 会被标记为需要设置，直到当前模式拥有全部三个密钥；沙盒模式开启期间还会显示测试模式标识。
保存时会校验密钥。Merchant ID 只能包含字母和数字，私钥必须以 sk_ 开头，公钥必须以 pk_ 开头。无效的值不会被保存：保留原值并显示错误，例如 Sandbox: The private key must start with sk_. 如果付款方式已启用但当前模式的密钥不完整，您还会看到一条提示，说明网关在结账时仍保持隐藏。
常规
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：Use the OpenPay sandbox (test keys, no real charges) 会将密钥和 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_...）。
插件 1.0 版本中的密钥（一组密钥加一个沙盒标志）会自动转移到沙盒或正式环境字段中。
Webhook
Webhook 不是必需的，但建议配置。当顾客没有从 3D Secure 页面返回时（例如关闭了浏览器），它可以确认付款。在 OpenPay 控制面板中进入 Settings > Webhooks，并添加本设置部分显示的 URL。它的格式类似：https://your-site/wc-api/webhook_wc_openpay/。请与设置中显示的内容完全一致地复制。请在您使用的每个模式的控制面板（沙盒和正式环境）中添加该 Webhook。
添加 Webhook 时，OpenPay 会向该 URL 发送一个验证码。该验证码会连同收到日期显示在本部分中，以便您在 OpenPay 控制面板中确认 Webhook。
请选择以下事件：
OpenPay 不对 Webhook 进行签名，因此插件从不信任通知本身。它只用通知来查找扣款，然后使用订单付款时所处模式的私钥从 OpenPay API 读取扣款信息。对于本店铺未创建的扣款的通知会被忽略。
高级
Debug log：Log payment steps (errors are always logged) 会将付款步骤写入 WooCommerce > Status > Logs，来源为 wcp_openpay_gateway。即使关闭，错误和警告也会被记录。密钥、银行卡数据和顾客信息绝不会被记录。默认：关闭。
Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。默认：关闭。
结账
顾客选择付款方式（默认为 Credit or debit card (OpenPay)），并填写 Cardholder name、Card number、Expiry (MM/YY) 和 Card code (CVV)。下单时，openpay.js 会在浏览器中将银行卡转换为一次性令牌，OpenPay 的反欺诈库会添加设备会话 ID。仅这两个值会被发送到您的店铺。
随后，插件会以订单货币、按订单总额创建带 3D Secure 的扣款，并将顾客引导至其银行的 3D Secure 页面（由 OpenPay 提供）。每次尝试都会在 OpenPay 中获得各自的订单参考号（订单号加一个简短后缀）。扣款描述为 Order #、订单号和您的网站名称。顾客的姓名、电子邮件和电话会传递给 OpenPay；不会在 OpenPay 中创建客户账户。顾客停留在 3D Secure 页面期间，订单保持 待付款 状态。
顾客返回后，插件会从 OpenPay API 读取扣款信息。只有在 OpenPay 确认之后，订单才会被标记为已付款：扣款必须属于该订单，已完成，并且与订单总额和货币完全一致。如果结果尚不确定，订单接收页面会显示 We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. 之后由 Webhook 更新订单。
如果银行卡被拒绝或 3D Secure 失败，顾客会返回 Pay for order 页面，并看到 The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card.，然后可以再次付款。在进行新的尝试之前，插件会检查订单的上一笔扣款：如果该笔扣款实际已付款，则直接将订单标记为已付款，不会重复扣款；如果仍在处理中，顾客会看到上一笔付款仍在处理，不应再次付款；如果无法确认其状态，则不进行新的尝试，并提示顾客几分钟后重试。
被拒绝的银行卡会显示清晰的提示，例如 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 的技术错误绝不会显示给顾客；它们会写入订单备注和日志。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。在禁用时、当前模式的密钥不完整时，或订单货币不被账户所在国家接受时，结账页面会隐藏该付款方式。
插件仅接受银行卡付款，且立即捕获。不支持保存的银行卡、订阅、免息分期（MSI）或分期付款、信用卡积分付款、现金、SPEI、PSE 或 CoDi 付款，也不支持单独的授权与捕获。
订单与退款
订单状态
待付款：顾客正在 3D Secure 页面，或尚未完成付款。备注会显示扣款 ID。
处理中：付款已确认。这是付款后 WooCommerce 的标准状态；仅包含虚拟可下载商品的订单会变为已完成。订单备注会显示扣款 ID 和模式（正式或沙盒）。交易 ID 为 OpenPay 扣款 ID。
保留：扣款正在进行且尚未捕获；或 OpenPay 报告了一笔金额或货币与订单不同的已完成扣款（订单不会被标记为已付款，备注会显示差异）；或者已取消的订单又收到了付款。请在 OpenPay 控制面板中检查订单，然后在那里完成订单或退款。
失败：创建扣款时银行卡被拒绝，或最近一次尝试失败、被取消或已过期。顾客可以再次付款。
如果已付款的订单又收到了第二笔已完成的扣款，订单不会被更改。以 WARNING 开头的备注会提示您在 OpenPay 控制面板中退还重复的扣款。
退款
对于墨西哥和秘鲁的账户：打开订单，点击 Refund，输入金额，然后点击 Refund via Credit or debit card (OpenPay)（按钮会显示您的付款方式名称）。支持全额和部分退款。退款会以订单付款时所用的模式和账户国家发送，因此在仍有沙盒订单需要退款时，请保留沙盒密钥的填写。如果 OpenPay 不接受退款，WooCommerce 会显示错误，例如 OpenPay refund failed: ...，并且不会记录任何退款。成功的退款会连同 OpenPay 退款 ID 一起添加到订单备注中。
与官方 OpenPay 插件一样，OpenPay Colombia 不支持通过 API 进行银行卡退款。对于哥伦比亚，不提供退款按钮；请在 OpenPay 控制面板中退款。
在 OpenPay 控制面板中进行的退款和拒付会通过 Webhook 送达，并且每条只会添加一次到订单备注中。它们不会自动记录为 WooCommerce 退款。如有需要，请在 WooCommerce 中创建手动退款，而不要使用 OpenPay 按钮。
许可证密钥
本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > OpenPay 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
如果没有有效的密钥，结账时顾客将看不到 OpenPay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也照常工作。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时不显示 OpenPay：请检查许可证是否有效、Enable / Disable 是否已开启，以及当前模式是否拥有全部三个密钥：沙盒模式使用沙盒密钥，正式模式使用正式密钥。检查店铺货币是否被 Account country 接受（墨西哥：MXN、USD；哥伦比亚：COP、USD；秘鲁：PEN、USD）。设置页面会在每种情况下显示警告。
付款已完成，但订单仍为待付款：顾客没有从 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。
顾客看到 The secure card form could not be loaded：openpay.js 或 OpenPay 的反欺诈库未能在浏览器中加载，或无法创建设备会话 ID。请让顾客刷新页面后重试。
顾客看到 The payment could not be processed right now：OpenPay 拒绝了请求或没有响应。原因记录在订单备注和日志中，来源为 wcp_openpay_gateway。典型原因是 Merchant ID 或私钥错误。如果 OpenPay 没有响应，请在顾客再次付款前，在 OpenPay 控制面板中检查该扣款。
This test card cannot be used for real payments：在沙盒模式关闭时使用了沙盒测试卡。
付款后订单处于保留状态：请阅读订单备注。扣款仍在进行，已付金额或货币与订单不一致，或付款是在订单取消之后到达的。
退款时出现与模式相关的错误信息：订单是在沙盒或正式模式下付款的，但该模式的密钥未设置。请输入密钥后重试。
许可证区块显示错误：请按照区块中的提示操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额并点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用上次已知的状态。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、已保存的 Webhook 验证码和插件日志只有在开启了 Delete data on uninstall 时才会被删除；否则会保留，以便日后重新安装。订单数据始终会保留：现有订单会保留其付款备注、交易 ID，以及重新安装后退款所需的扣款数据。
OpenPay 是其各自所有者的商标。本插件与 OpenPay 无关联，也未获得 OpenPay 的认可。