VibeFox Conekta for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法激活。

PHP：8.0 或更高版本。

货币：店铺货币必须为 MXN 或 USD。使用其他货币时，付款方式将被隐藏。

Conekta 账户：您需要 Conekta 账户的 Private Key（测试和正式模式各一个）以及 Conekta 控制面板中的 Webhook（参见「配置」）。仅使用 Private Key。无需 Public Key，因为付款在 Conekta 托管的付款页面上完成。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_conekta_gateway 文件夹上传至 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Conekta > Manage，或在插件页面上点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入测试和正式 Private Key，选择模式，并在 Conekta 控制面板中添加 Webhook（参见「配置」）。

6. 开启 Enable / Disable 并保存。在测试模式下测试一笔付款，然后取消勾选 Test mode。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > Conekta。在字段上方，如果已启用 Conekta 但当前模式的 Private Key 为空（此时付款方式在结账页面中隐藏），或店铺货币不是 MXN 或 USD，页面会向您发出警告。开启测试模式时，页面会显示 Test mode is on: payments are simulated with the test private key. 如果在保存已启用的网关时未填写当前模式的密钥，将弹出错误消息，要求您填写。

常规

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

Title：顾客在结账页面看到的付款方式名称。默认：Conekta。

Description：结账页面上显示在付款方式下方的文字。默认：Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods：Conekta 付款页面上提供的付款方式。默认：银行卡、现金和银行转账。现金、SPEI 和 BNPL 仅适用于 MXN 订单（USD 订单仅支持银行卡），并且必须在您的 Conekta 账户中启用。若未选择任何方式，则使用银行卡。

Credit / debit card：银行卡付款。

Cash (OXXO and other stores)：顾客获得一个参考号，并在门店付现金。

Bank transfer (SPEI)：顾客获得一个参考号，并通过银行转账付款。

Buy now, pay later (BNPL)：通过 BNPL 选项付款（前提是您的 Conekta 账户已启用该选项）。

API 密钥

请在 Conekta 控制面板的 Developers > API keys 中复制您的 Private Key。测试和正式密钥各不相同。

Test mode：Enable test mode 使用测试 Private Key。不会扣除真实款项，结账页面会显示 TEST MODE 标识。退款始终使用付款时所处模式的密钥。默认：开启。

Test private key：您的 Conekta 账户测试模式中的 Private Key。

Live private key：您的 Conekta 账户正式模式中的 Private Key。请妥善保密。

每个 Conekta 订单都会记住其所属模式：通知和退款会使用对应的密钥。在旧的测试订单仍处于打开状态时，请保持两个密钥都已填写。

Webhook

Webhook 用于告知您的店铺：顾客离开 Conekta 页面后完成的付款，例如 OXXO 或 SPEI 付款。在 Conekta 控制面板中进入 Developers > Webhooks，并分别为测试模式和正式模式添加本节所示的 URL。其格式如下：https://your-site/wc-api/webhook_wc_conekta/。

请选择以下事件：

order.paid：订单已付款。

order.pending_payment：订单正在等待付款，例如已生成 OXXO 或 SPEI 参考号时。

order.declined：付款被拒绝。

order.expired：付款页面或付款参考号已过期。

order.canceled：Conekta 订单已取消。

order.refunded：付款已退款，例如在 Conekta 控制面板中退款。

order.charged_back：顾客对付款提出争议（拒付）；插件会添加订单备注。

Webhook 内容仅告诉插件哪个 Conekta 订单发生了变化。每条通知都会使用该模式的 Private Key，通过 Conekta API 重新读取订单进行验证；不使用 Webhook 的 Digest 签名标头。对于并非由本店铺为该订单创建的 Conekta 订单通知，系统会予以接收并忽略。如果没有 Webhook，只有在顾客付款后返回店铺，或在同一订单的下一次付款尝试时，才会确认订单。

高级

Debug log：Log API calls and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_conekta_gateway。错误始终会被记录。日志绝不包含 API 密钥或顾客联系信息。默认：关闭。

Delete data on uninstall：Remove the settings, Conekta order references and logs when the plugin is deleted。默认：关闭。

结账

顾客选择付款方式（默认为 Conekta）并提交订单。插件会按订单币种为订单总额创建 Conekta 订单，并包含订单商品、运费、税费和折扣，然后将顾客带到 Conekta 托管的付款页面。顾客在该页面使用允许的付款方式之一完成付款。

付款完成后，顾客返回您的店铺。只有在 Conekta 确认之后，订单才会标记为已付款：插件会在收到 Webhook 时以及顾客返回时，通过 Conekta API 读取订单。如果付款暂时无法确认，订单已收到页面会显示 We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. 如果顾客选择了 OXXO 或 SPEI 并获得了付款参考号，订单将进入「保留」状态，页面会显示 Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.

如果付款被拒绝，订单将标记为「失败」，顾客会返回 Pay for order 页面，并看到 The Conekta payment was not completed. Please try again or choose another payment method. 如果付款页面已过期或被取消，顾客会看到 The Conekta payment has expired or was cancelled. Please place the order again. 当顾客重新支付某个订单时，如果存在金额相同且仍处于打开状态的 Conekta 付款页面，则会复用该页面；否则，会先在 Conekta 中取消之前的页面，再创建新的页面，以免旧链接被支付两次。如果之前的付款页面已经完成付款，则会记录该笔付款，而不会再次扣款。

如果 Conekta 无法发起付款，顾客会看到一条简短消息，例如 The payment could not be started. Please try again in a moment or choose another payment method. 技术原因会写入日志。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce High-Performance Order Storage (HPOS)。这些文本已翻译为西班牙语（墨西哥）。

插件仅在 Conekta 页面上接收付款。结账页面上没有银行卡表单，不支持保存的银行卡、订阅、预授权和扣款，也不支持按月分期（MSI）。

订单和退款

订单状态

Pending payment：顾客已被转至 Conekta，但尚未付款。订单备注中会显示 Conekta 订单及模式。

Processing：Conekta 已确认付款，金额和币种与订单一致（仅包含虚拟可下载商品的订单会变为「已完成」，即 WooCommerce 默认行为）。订单备注中会显示付款方式（例如银行卡品牌及后四位数字、OXXO / 现金或 SPEI 银行转账）、Conekta 订单和扣款信息。订单的交易 ID 即 Conekta 扣款 ID（charge ID）。

On hold, waiting for OXXO or SPEI：顾客已获得付款参考号。当 Conekta 报告付款后，订单将变为「处理中」。

On hold after payment：从 Conekta 收到的金额或币种与订单不符；店铺处于正式模式时收到了测试模式付款（未收取真实款项）；或付款针对的是已取消的订单。订单备注会说明原因。请检查付款，然后完成订单或将其退款。仅在 Conekta 中预授权的订单也会被置于「保留」状态，并附带备注，提示您在 Conekta 控制面板中进行扣款或撤销。

Failed：付款被拒绝。备注中会显示原因。顾客可以重新付款。

Cancelled：当前的 Conekta 付款页面已过期或被取消。

已付款或已退款的订单绝不会降级或重新打开。如果已付款的订单又收到其他 Conekta 付款，将添加一条 WARNING 备注，提示您在 Conekta 控制面板中对其进行退款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Conekta（按钮会显示付款方式名称）。支持全额和部分退款。退款会发送至包含该笔付款的 Conekta 订单，并使用付款时所处模式的密钥，因此必须已设置该密钥。如果 Conekta 不接受退款，WooCommerce 会显示错误，且不会记录退款。成功的退款会以金额、模式、Conekta 订单、退款 ID 和原因的形式添加到订单备注中。

在 Conekta 控制面板中进行的退款会通过 Webhook 送达，并以备注形式添加，同时记录在 Conekta 中退还的金额和在 WooCommerce 中的金额。这些退款不会自动记录为 WooCommerce 退款。请在不使用 Refund via Conekta 的情况下手动记录。Conekta 报告的拒付同样会以备注形式添加。

许可证密钥

本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Conekta 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 可再次检查状态，使用 Change key 可输入其他密钥，使用 Remove key 可将其从本站点移除。链接 Manage licenses and domains in your account 可打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

如果没有有效的密钥，Conekta 不会在结账页面向顾客显示。即使如此仍发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。

许可证过期后，插件仍会继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

Conekta 未在结账页面显示：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的 Private Key 是否已填写（测试模式为 Test private key，正式模式为 Live private key），以及店铺货币是否为 MXN 或 USD。设置页面会针对上述每项条件显示警告。

付款已完成，但订单仍处于 Pending payment 状态：Webhook 无法正常工作。请在 Conekta 控制面板中检查您所用模式（测试或正式）的 Webhook 是否存在，其 URL 是否与设置中显示的完全一致，以及是否已选择相应事件。请检查该模式的 Private Key 是否已设置，因为每条通知都会使用它进行验证。当顾客返回店铺或再次尝试支付同一订单时，订单也会被确认。

Webhook 返回 Temporarily unavailable：无法连接 Conekta API，订单所属模式的 Private Key 缺失，或订单正在被另一个请求处理。Conekta 会重试该 Webhook。

Webhook 返回 Verification failed、Invalid payload 或 Invalid order id：Conekta API 未能确认该订单，或该通知并非有效的 Conekta 订单事件。

Webhook 返回 Ignored：该通知所属的 Conekta 订单并非由本店铺为此订单创建（例如其他店铺，或同一账户上的付款链接），或其对象不是订单。

顾客看到 We could not check the status of your previous payment attempt：无法读取该订单之前的 Conekta 付款页面，因此不会创建新的付款页面，以避免重复付款。请稍后重试。

顾客看到 Payment gateway is not configured：当前模式的 Private Key 缺失。

订单处于 On hold 状态：请阅读订单备注。顾客尚未支付 OXXO 或 SPEI 参考号，金额或币种不匹配，或者店铺处于正式模式时收到了测试模式付款。

退款失败，并显示与测试或正式模式相关的消息：该笔付款是在该模式下完成的，但对应的 Private Key 未设置。请输入该密钥后重试。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已用于其他域名，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用最近一次已知的状态运行。

对于开发者：readme 中列出了用于设置货币列表的过滤器 wc_ckt_supported_currencies。

卸载

停用插件将保留所有数据。若要删除，请先停用，然后在 Plugins 页面中将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、保存在订单中的 Conekta 引用以及日志，只有在开启 Delete data on uninstall 时才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注和交易 ID。

Conekta 为其各自所有者的商标。本插件与 Conekta 无关联，也未获得 Conekta 的认可或背书。