VibeFox Conekta for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

货币：购物车货币必须为 MXN 或 USD。对于其他货币，将隐藏该付款方式。

Conekta 账户：您需要 Conekta 账户的私有 API 密钥（测试和正式）以及 Conekta 控制面板中的 Webhook（参见配置）。仅使用私有密钥。无需公钥，因为付款在 Conekta 托管的付款页面上完成。

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

安装

1. 在后台进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox Conekta Gateway 并点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 输入您的测试和正式私钥，选择模式，并在 Conekta 控制面板中添加 Webhook（参见配置）。

5. 开启 Enable / Disable 并点击 Save。在测试模式下测试一笔付款，然后关闭 Test mode。

安装时，模块会创建两个订单状态：Awaiting Conekta payment 和 Conekta payment on hold。PrestaShop 会为所有货币、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Conekta Gateway > Configure。每个部分都有自己的 Save 按钮，该按钮会保存整个页面。在字段上方，如果已启用 Conekta 但当前模式的私钥为空（此时该付款方式会在结账时隐藏），或店铺的默认货币不是 MXN 或 USD，页面会向您发出警告。测试模式开启时，页面会显示 测试模式已开启：付款将使用测试私钥进行模拟。 如果您在未填写当前模式密钥的情况下保存已启用的网关，系统会提示您输入该密钥。

Conekta

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 付款页面上提供的付款方式。默认：card, cash and bank transfer。现金、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 下复制您的私钥。测试密钥和正式密钥是不同的。

Test mode：使用测试私钥。不会扣除真实款项，结账时付款方式下方会显示 TEST MODE 标识，并附带 不会产生任何真实扣款。 提示。退款始终使用付款时所处模式的密钥。默认：开启。

Test private key：您 Conekta 账户测试模式的私有 API 密钥。

Live private key：您 Conekta 账户正式模式的私有 API 密钥。请妥善保密。

已保存的密钥不会再次显示。该字段将保持为空，并显示 已保存——留空即可保留。 仅在需要更改时才输入新值。

Clear saved keys：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。

每个 Conekta 订单都会记住其所属模式：通知和退款会使用对应的密钥。在旧的测试订单仍未关闭期间，请保持两个密钥都已填写。

Webhook

Webhook 用于告知您的店铺有关付款的信息，例如顾客离开 Conekta 页面后完成的 OXXO 或 SPEI 付款。在 Conekta 控制面板中，进入 Developers > Webhooks，并分别为测试模式和正式模式添加 API keys 部分中 Webhook 字段所显示的 URL。启用友好 URL 时，它的形式类似于 https://your-shop/module/wcp_conekta_gateway/webhook，可能还会带有语言代码，例如 /en/。请完全按照设置中显示的内容复制该 URL。

请选择以下事件（它们也列在设置中）：

order.paid：订单已付款。

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

order.declined：付款被拒绝。

order.expired：结账或付款参考号已过期。

order.canceled：Conekta 订单已取消。

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

order.charged_back：顾客对付款提出异议（拒付）；模块会在订单中添加备注。

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

高级

Debug log：将 API 调用和通知记录到模块文件夹中的 logs/wc_ckt_debug.log.php。该文件无法通过网页打开。即使此开关关闭，错误和警告也始终会被记录。日志绝不包含 API 密钥或顾客联系信息。默认：关闭。

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

Delete data on uninstall：开启后，卸载模块时将删除设置和日志。Conekta 交易和退款、订单状态以及订单始终会被保留，因此重新安装后仍可确认和退款旧订单。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 Conekta）并确认。模块会按购物车币种为购物车总额创建 Conekta 订单，其中包括商品、礼品包装、折扣、税费和运费，并将顾客带到 Conekta 托管的付款页面。付款在 Conekta 页面上显示为 Order # 和购物车编号。顾客在此使用允许的付款方式之一完成付款。此时尚不存在订单。

付款后，顾客返回您的店铺。只有在 Conekta 确认后，订单才会被标记为已付款：模块会在 Webhook 到达时以及顾客返回时，从 Conekta API 读取订单。随后订单会被创建，顾客会看到标准订单确认页面，显示 Conekta 付款已收到。 如果顾客选择了 OXXO 或 SPEI 并获得了付款参考号，订单将以 Awaiting Conekta payment 状态创建，页面会显示 Conekta 付款参考号已发出。付款一经收到，订单将随即确认。 如果参考号之后过期，订单将被取消，其确认页面会显示 Conekta 付款未完成。请就此订单与我们联系。

如果顾客返回时付款尚无法确认，付款确认页面会显示 我们正在与 Conekta 确认您的付款。订单将自动更新——请勿重复付款。 以及 Check again 按钮。Webhook 一到达就会创建订单。

如果付款被拒绝，将不会创建订单，顾客会返回结账页面，并显示 Conekta 付款未完成。请重试或选择其他付款方式。 如果结账已过期或被取消，提示信息为 Conekta 付款已过期或已取消。请重试。 购物车会被保留。当顾客再次付款时，将复用金额相同且仍处于打开状态的 Conekta 付款页面；否则，在创建新页面之前会先在 Conekta 中取消之前的页面，确保旧链接不会被支付两次。如果之前的页面已经付款，则直接创建订单，而不会再次扣款。

如果 Conekta 无法启动付款，顾客会停留在结账页面，并显示一条简短提示，例如 无法启动付款。请稍后重试或选择其他付款方式。 Conekta 发送的验证信息（例如最低金额）会按 Conekta 发送的内容显示。技术原因会记录在日志中。

即使店铺处于维护模式，Webhook 仍可正常工作，且不受店铺国家限制的影响。

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

订单和退款

订单状态

No order yet：顾客已被转至 Conekta 但尚未付款，付款被拒绝，或 Conekta 尚未确认付款。此时仅存在购物车。

Payment accepted：Conekta 已以相同金额和币种确认付款。付款以 Conekta 扣款 ID 作为交易 ID 记录，备注中会显示付款方式（例如银行卡品牌及后四位数字、OXXO / 现金或 SPEI 转账）、Conekta 订单和扣款信息。

Awaiting Conekta payment：顾客获得了 OXXO 或 SPEI 付款参考号。当 Conekta 报告付款后，订单将变为 Payment accepted。

Conekta payment on hold：从 Conekta 收到的金额或币种与购物车不符（例如付款开始后购物车被修改），在店铺处于正式模式时收到测试模式付款（未收取真实款项），或为已取消的订单收到付款。备注会说明原因，付款将按实际支付的金额记录。请检查订单，然后处理订单或退还付款。仅在 Conekta 中完成预授权的订单同样会被暂停，并附带备注，提示您在 Conekta 控制面板中进行扣款或作废。

Canceled：等待中订单的 OXXO 或 SPEI 参考号已过期，或其 Conekta 订单已取消。

Refunded：付款已通过模块全额退款。

已付款或已退款的订单绝不会降级或重新打开。如果已付款的订单又收到另一笔 Conekta 付款，WARNING 备注会提示您在 Conekta 控制面板中退款。

Conekta 付款区块

订单页面会显示 Conekta payment 区块，其中包括 Conekta 订单、扣款、付款状态、已付和已退款金额、测试付款的 Test mode 标识、退款记录以及订单的 Conekta notes。

退款

在 Conekta payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Conekta。确认提示 是否通过 Conekta 退还此金额？此操作无法撤销。 支持全额和部分退款。您需要具备编辑订单的权限。退款金额和币种以 Conekta 实际收取的为准，因此在金额不一致后，您最多只能退还顾客已支付的金额，而不是订单总额。退款会发送到包含该付款的 Conekta 订单，并使用付款时所处模式的密钥，因此该密钥必须已设置。如果 Conekta 不接受退款，区块会显示错误，且不会记录任何退款。退款成功后，会将金额、模式、Conekta 订单、退款 ID 和原因添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。退款在 Conekta 报告付款后即可进行。

模块不会生成信用单。订单页面中 PrestaShop 的标准退款按钮不会通过 Conekta 退回款项。

在 Conekta 控制面板中进行的退款会通过 Webhook 到达，并以备注形式添加，其中包含在 Conekta 和 PrestaShop 中的退款金额。这些退款不会自动记录。请手动更新订单，而不要使用 Refund via Conekta。Conekta 报告的拒付也会以备注形式添加。

许可证密钥

本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Conekta Gateway 许可证区块是 Modules > Module Manager > VibeFox Conekta Gateway > Configure 页面上位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-conekta 一行，以及一个链接“在您的账户中管理许可证和域名”，点击后将打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

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

一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺移除密钥不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。

如果没有有效的密钥，Conekta 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 此付款方式不可用。请选择其他方式。 PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款也仍可正常进行。

许可证到期后，模块仍可继续运行，但更新和支持需要续费。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块将始终删除许可证密钥和许可证状态。

故障排除

Conekta 未出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，当前模式的私钥是否已填写（测试模式为 Test private key，正式模式为 Live private key），以及购物车币种是否为 MXN 或 USD。如果缺少密钥或店铺币种不受支持，设置页面会显示警告。在 Payment > Preferences 中，检查模块是否允许用于该购物车币种、顾客所在国家和顾客所属群组。

付款已完成，但未创建订单：Webhook 无法正常工作。请在 Conekta 控制面板中检查，您所用模式（测试或正式）的 Webhook 是否存在，其 URL 是否与设置中显示的完全一致，以及事件是否已选择。检查该模式的私钥是否已设置，因为每个通知都要使用它进行验证。当顾客返回店铺或再次尝试付款同一购物车时，也会创建订单。

Webhook 返回 Temporarily unavailable：无法连接 Conekta API，订单所属模式的私钥缺失，购物车正在被另一个请求处理，或订单无法创建（例如模块已禁用）。Conekta 会重试 Webhook。请查看 Log 字段以了解原因。

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

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

Webhook 网址在浏览器中显示 Method not allowed：这是正常现象。该网址只接受来自 Conekta 的请求。

顾客看到「无法检查您之前的付款尝试状态」：无法读取该购物车之前的 Conekta 付款页面，因此不会创建新页面，以避免重复付款。请稍后重试。

顾客看到「付款网关未配置」：当前模式的私钥缺失。

顾客看到「付款验证失败」：Conekta 的返回链接与购物车不匹配。请在 Conekta 控制面板中检查该订单；Webhook 仍会确认真实的付款。

订单处于 Awaiting Conekta payment 或 Conekta payment on hold 状态：请阅读订单区块中的 Conekta notes。顾客尚未支付 OXXO 或 SPEI 参考号，金额或币种不匹配，店铺处于正式模式时收到了测试模式付款，或该付款仅为预授权。

退款失败，提示测试或正式模式相关信息：付款是在该模式下完成的，而其私钥尚未设置。请输入该密钥后重试。

对于开发人员，README 列出了以下钩子：actionWcpConektaSupportedCurrencies、actionWcpConektaOrderRequest、actionWcpConektaAllowedPaymentMethods 和 actionWcpConektaRefundReason。

卸载

进入 Modules > Module Manager，打开 VibeFox Conekta Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被移除。如果 Delete data on uninstall 已开启，设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Conekta 交易和退款以及 Awaiting Conekta payment 和 Conekta payment on hold 订单状态始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。

Conekta 是其各自所有者的商标。本模块与 Conekta 无关联，也未获得 Conekta 的认可。