VibeFox Conekta for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：结账货币必须是 MXN 或 USD。其他货币下，付款方式会被隐藏。

Conekta 账户：您需要 Conekta 账户的私有 API 密钥（测试和正式）以及 Conekta 后台的一个 Webhook（参见 Configuration）。只使用私有密钥。不需要公开密钥，因为付款是在 Conekta 托管的结账页面上完成的。

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

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_conekta_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_conekta_gateway.ocmod.zip。只安装适合您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 输入测试和正式私有密钥，选择模式，并在 Conekta 后台添加 Webhook（参见 Configuration）。

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

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_conekta_gateway.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包无法工作。

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

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

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

新安装默认关闭付款方式，并开启测试模式。

Configuration

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Conekta Gateway > Edit。设置分区列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果 Conekta 已启用但当前模式的私有密钥为空（此时结账时会隐藏付款方式），或者店铺的默认货币不是 MXN 或 USD，页面会向您发出警告。开启测试模式时，页面会显示 Test mode is on: payments are simulated with the test private key. 如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空，Sort Order 必须是整数，Total 必须是非负数，所选的地理区域和订单状态必须存在。如果任何检查失败，则不会保存任何内容，页面会列出错误。以下两项警告不会阻止保存：未选择任何付款方式时（此时会提供银行卡付款），以及在没有当前模式私有密钥的情况下启用了网关时。

Conekta

Enable / Disable：Enable Conekta payments 用于开启或关闭付款方式。Default：off。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。Default：Conekta。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。Default：Pay securely with card, OXXO cash or SPEI transfer. 您将被重定向到 Conekta 完成付款。

Payment methods：Conekta 付款页面上提供的付款方式。Default：card, cash and bank transfer。现金、SPEI 和 BNPL 仅适用于 MXN 订单（USD 订单只能使用银行卡），并且必须在您的 Conekta 账户中启用。如果未选择任何方式，则使用银行卡。

Sort Order：Conekta 在结账时的付款方式中的排列位置。可留空或输入整数。

Geo Zone：仅为所选地理区域内的付款地址提供 Conekta。Default：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以店铺默认货币计算），达到后才会提供 Conekta。留空则对任意金额都提供 Conekta。

API 密钥

从 Conekta 后台的 Developers > API keys 复制您的私有密钥（页面中有指向后台的链接）。测试密钥和正式密钥是不同的。

Test mode：使用测试私有密钥。不会扣除真实款项，顾客在 Confirm Order 步骤会看到 TEST MODE — No real charges will be made. 退款始终使用付款时所处模式的密钥。Default：on。

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

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

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

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

Webhook

Webhook 会将付款信息告知您的店铺，例如顾客离开 Conekta 页面后完成的 OXXO 或 SPEI 付款。在 Conekta 后台进入 Developers > Webhooks，为测试模式和正式模式分别添加本节 Webhook URL 中显示的 URL。在 OpenCart 3 中它类似于 https://your-store/index.php?route=extension/payment/wcp_conekta_gateway/webhook，在 OpenCart 4 中类似于 https://your-store/index.php?route=extension/wcp_conekta_gateway/payment/wcp_conekta_gateway.webhook，由您 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制该 URL。它必须可以从互联网访问。

请选择以下事件（本节也列出了这些事件）：

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

订单

OpenCart 在 Confirm Order 步骤创建订单，此时没有状态（缺失订单）。只有在 Conekta 报告付款之后（通过 Webhook 或顾客返回时），订单才会获得状态；订单总是从 Conekta 重新读取。下方的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：经验证的 Conekta 付款后设置的状态。Default：Processing。

Awaiting Conekta Payment Status：已向顾客发出 OXXO 或 SPEI 付款参考号，但 Conekta 尚未收到款项。Default：Pending。

Conekta Payment On Hold Status：已付款，但金额或币种与订单不符，正式模式下收到了 TEST 付款，订单已被取消，或者付款只是预授权。备注会说明原因。Default：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Expired / Canceled Status：等待付款的订单，其 Conekta 参考号已过期，或其 Conekta 订单已被取消。Default：Canceled。

Refunded Status：在订单页面中全额退款后设置。Default：Refunded。

高级

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

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

Delete data on uninstall：开启时，卸载扩展会删除设置和日志。Conekta 交易、退款以及订单始终会被保留，因此旧订单在重新安装后仍可确认和退款。Default：off。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Conekta）。在 Confirm Order 步骤中，顾客会看到您的说明以及备注 You will be redirected to Conekta to complete your payment. OpenCart 在此步骤创建订单，仍然没有状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额创建一个 Conekta 订单，其中包含商品、附加费、折扣、税费和运费，并将顾客带到 Conekta 托管的结账页面。顾客的姓名、电子邮件、电话和收货地址会传递给 Conekta，付款在 Conekta 页面上显示为 Order # 及订单号。顾客在那里使用允许的付款方式之一完成付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。如果店铺不要求付款地址（OpenCart 4 默认设置），则账单信息取自收货地址和顾客姓名。

付款后，顾客返回您的店铺。只有在 Conekta 确认之后，订单才会被标记为已付款：扩展会在 Webhook 到达时以及顾客返回时，通过 Conekta API 读取订单。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面。如果顾客选择了 OXXO 或 SPEI 并获得了付款参考号，订单会获得 Awaiting Conekta Payment Status，成功页面会显示 Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received. 对于处于保留状态的订单，页面会显示 We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again.

如果顾客返回时仍无法确认付款，Payment confirmation 页面会显示相同文字以及 Check again 按钮。Webhook 一到达就会设置订单状态。在 OpenCart 4 中，顾客被 Conekta 送回时浏览器不会发送店铺会话，因此扩展会先显示一个短暂页面，从您的店铺再次打开同一返回地址：顾客会保留购物车和登录状态。

如果付款被拒绝，订单保持无状态，顾客会返回结账页面，并显示 The Conekta payment was not completed. Please try again or choose another payment method. 如果结账已过期或被取消，消息为 The Conekta payment has expired or was cancelled. Please try again. 在 OpenCart 4 中，这些消息显示在结账页面上方。购物车会被保留。每次新的尝试（OpenCart 3 在每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 为结账保留一个订单并对其进行更新）都会先读取该购物车之前的 Conekta 结账记录。同一订单、相同金额的未完成结账会被重复使用；否则，在创建新结账之前，会先在 Conekta 中取消之前的结账，以防旧链接被重复付款。如果之前的结账已经付款，则其订单会被确认，而不会再次扣款。每个购物车只付款一次：当同一购物车的另一订单已有 Conekta 付款或已发出 OXXO / SPEI 参考号时，不会启动新的付款，顾客会被带到成功页面。如果同一购物车仍然收到第二笔付款，该订单保持无状态，已付款的订单会收到一条备注，提示在 Conekta 后台退还这笔重复付款。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单此时已被关闭（例如其 OXXO 或 SPEI 参考号已过期，或您取消了它），Confirm Order 会将顾客带回结账页面，并显示 The Conekta payment has expired or was cancelled. Please try again.，随后的 Confirm Order 会为该购物车支付一个新订单。如果订单已有状态，且此后购物车发生了变化（其他商品或数量），顾客会被送回结账页面，变更后的购物车会获得新订单及其自己的付款。

如果 Conekta 无法启动付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息，例如 The payment could not be started. Please try again in a moment or choose another payment method. Conekta 发出的验证消息（例如最低金额）会按照 Conekta 发送的内容显示。技术原因会记录在日志中。

即使店铺处于维护模式，Webhook 仍然有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，该扩展会为 Webhook 添加一个启动操作。

该扩展仅在 Conekta 页面上接受付款。您的结账页面上没有银行卡表单，也不支持保存的银行卡、订阅、预授权和捕获，或分期付款（MSI）。

订单与退款

订单状态

无状态（缺失订单）：顾客已被发送到 Conekta 但尚未付款，付款被拒绝，或 Conekta 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时，才会显示此类订单。

Order Status After Payment（默认 Processing）：Conekta 已以相同金额和币种确认付款。备注会显示付款方式（例如银行卡品牌及后四位数字、OXXO / 现金或 SPEI 转账）、Conekta 订单和扣款信息。

Awaiting Conekta Payment Status（默认 Pending）：顾客获得了 OXXO 或 SPEI 付款参考号。当 Conekta 报告付款后，订单会转为 Order Status After Payment。

Conekta Payment On Hold Status（默认 Pending）：从 Conekta 收到的金额或币种与订单不符；店铺处于正式模式时收到了测试模式付款（未收取真实款项）；或者付款针对的是已被取消的订单。备注会说明情况。请检查订单，然后处理订单或退还付款。在 Conekta 中仅为预授权的订单也会被置于保留状态，并附带备注，提示您在 Conekta 后台对其进行捕获或撤销。

Payment Expired / Canceled Status（默认 Canceled）：等待中订单的 OXXO 或 SPEI 参考号已过期，或其 Conekta 订单已被取消。

Refunded Status（默认 Refunded）：付款已通过该扩展全额退款。

已付款或已退款的订单绝不会被降级或重新打开。如果同一个已付款的订单又收到另一笔 Conekta 付款，会出现一条 WARNING 备注，要求您在 Conekta 后台退还该笔付款。

备注是订单 History 中顾客看不到的记录。

VibeFox Conekta Gateway 选项卡

在 Sales > Orders 中打开一个使用 Conekta 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Conekta Gateway 选项卡会显示 Conekta order（测试付款会带有 Test mode 标签）、Charge、付款的 Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 Conekta notes。该选项卡会显示给有权访问该扩展的用户。

退款

在 VibeFox Conekta Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Conekta。确认提示 Refund this amount through Conekta? This cannot be undone. 支持全额和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额和币种仅限于 Conekta 实际扣款的数额；因此，在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送到包含该付款的 Conekta 订单，并使用付款时所处模式的密钥，因此必须已设置该密钥。如果 Conekta 不接受退款，选项卡会显示错误，且不会记录任何退款。成功的退款会添加到退款历史和备注中，包括金额、模式、Conekta 订单、退款 ID 和原因。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。一旦 Conekta 报告付款，即可进行退款。

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

在 Conekta 后台进行的退款会通过 Webhook 送达，并作为备注添加，备注中包含在 Conekta 和 OpenCart 中退款的金额。这些退款不会被自动记录。请在不使用 Refund via Conekta 的情况下手动更新订单。Conekta 报告的拒付也会作为备注添加。

许可证密钥

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

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

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

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

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

故障排除

Conekta 没有出现在结账页面：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的私有密钥是否已填写（测试模式为 Test private key，正式模式为 Live private key），以及结账货币是否为 MXN 或 USD。当密钥缺失或店铺货币不受支持时，设置页面会显示警告。另外，还请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍然没有状态：Webhook 没有正常工作。请在 Conekta 后台检查，您所用模式（测试或正式）的 Webhook 是否存在，其 URL 是否与 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 URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Conekta 的请求。

顾客看到 We could not check the status of your previous payment attempt：无法读取该购物车之前的 Conekta 结账记录，因此为避免重复付款，没有创建新的结账。请稍后再试。

顾客看到 Payment gateway is not configured：当前模式的私有密钥缺失。

顾客看到 This payment method is not available.：结账会话已不再与订单匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

顾客看到 Payment verification failed：Conekta 的返回链接与订单不匹配。请在 Conekta 后台检查该订单；Webhook 仍会确认真实的付款。

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

选项卡中没有退款表单：选项卡会说明原因：Conekta 尚未报告该付款，该付款已全额退款，您的用户组没有修改扩展的权限，或该付款所用模式的私有密钥未设置。

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

对开发者：OpenCart 事件 wc_ckt_supported_currencies、wc_ckt_order_request、wc_ckt_allowed_payment_methods 和 wc_ckt_refund_reason 允许其他扩展修改支持的货币、Conekta 订单请求、付款方式和退款原因。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Conekta Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态（重新安装时恢复为默认值）。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件和使 Webhook 能在维护模式下通过的启动操作）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、说明、付款方式、测试模式、私有密钥、日志记录）和日志都会被删除。如果已关闭，它们会被保留，以便日后重新安装。Conekta 交易和退款始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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