VibeFox Culqi for WooCommerce — 帮助

系统要求

WordPress：5.8 或更高版本。

WooCommerce：6.0 或更高版本，已安装并启用。没有它，插件将拒绝激活。

PHP：8.0 或更高版本。

店铺币种：秘鲁索尔（PEN）或美元（USD）。Culqi 不接受其他币种，店铺使用其他币种时，该支付方式会在结账页面隐藏。

Culqi 账户：您需要 Culqi 账户的公钥和私钥。集成（测试）密钥来自 integ-panel.culqi.com，生产（正式）密钥来自 mipanel.culqi.com，位于 CulqiPanel > Desarrollo > API Keys。公钥由浏览器中的 Culqi 弹出窗口使用。私钥仅在您的服务器上使用，绝不会发送到浏览器。无需 Webhook。

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

安装

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

2. 点击 Activate。

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

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

5. 粘贴集成密钥；如需接收真实付款，还要粘贴生产密钥（参见「配置」）。

6. 打开 Enable/Disable。测试期间保持 Test Mode 开启，之后取消勾选即可接收真实付款。

7. 确认店铺币种为 PEN 或 USD。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > Culqi。测试模式开启时，页面会在字段上方显示 Test mode is active: the integration keys are used and no real money is charged.。当网关已启用但缺少当前模式的密钥，或店铺币种不受 Culqi 支持时，页面会发出警告。这两种情况下，该支付方式都会在结账页面隐藏。在支付方式列表中，在当前模式的两个密钥都设置好之前，Culqi 会被标记为需要设置。

常规

Enable/Disable: Enable Culqi Payment Gateway 用于开启或关闭该支付方式。默认：关闭。

Title: 顾客在结账页面看到的支付方式名称。默认：Credit/Debit Card or Yape (Culqi)。

Description: 在结账页面显示于支付方式下方的文字。默认：Pay securely with your credit/debit card or Yape via Culqi。

API 密钥

请从 CulqiPanel > Desarrollo > API Keys 复制密钥：集成（测试）密钥在 integ-panel.culqi.com，生产密钥在 mipanel.culqi.com。测试模式只使用测试密钥，正式模式只使用正式密钥。每个密钥必须以其字段对应的前缀开头。前缀错误的密钥不会被保存：页面会显示错误并保留之前的值。

Test Mode: Use the Culqi integration (test) environment。开启时使用测试密钥（pk_test_ / sk_test_），不会扣取真实资金。默认：开启。取消勾选后，将使用正式密钥接收真实付款。

Test Public Key: 集成环境的公钥。以 pk_test_ 开头。

Test Secret Key: 集成环境的私钥。以 sk_test_ 开头，绝不会与浏览器共享。

Live Public Key: 生产环境的公钥。以 pk_live_ 开头。

Live Secret Key: 生产环境的私钥。以 sk_live_ 开头，绝不会与浏览器共享。

如果您从 1.0 版本更新，该版本中的单一密钥对会根据前缀移动到测试或正式字段。更新后请检查密钥。

支付方式

始终提供银行卡支付。银行转账、代理点、电子钱包和 Cuotéalo 需要 Culqi Orders API，本插件不提供。

Yape: Offer Yape in the Culqi popup 会在 Culqi 窗口中于银行卡旁显示 Yape。默认：开启。

高级

Debug log: Log API requests and payment steps 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_culqi_payment。错误始终会被记录。密钥、银行卡数据和顾客信息绝不会被记录。默认：关闭。

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted。停用插件不会删除任何内容。保存在订单中的 Culqi 数据始终会保留。默认：关闭。

结账

顾客选择支付方式（默认为 Credit/Debit Card or Yape (Culqi)），然后点击下单按钮。Culqi Checkout 弹出窗口会在同一页面打开，显示您的店铺名称、订单总额和币种。顾客在窗口中输入银行卡信息或使用 Yape 付款。测试模式开启时，该支付方式会显示 TEST MODE: No real charges will be made.

Culqi 将付款数据转换为一次性令牌，结账请求连同该令牌一起发送到您的店铺。您的服务器使用 Culqi Charges API，按订单币种创建订单总额的扣款，并在扣款描述中写入订单号。只有在 Culqi 确认扣款，且扣款金额和币种与订单一致之后，订单才会标记为已付款。随后顾客会进入订单已收到页面。

如果银行要求 3-D Secure，顾客会看到 Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. 验证完成后，扣款会自动重新发送。如果验证未完成，顾客会看到 The 3-D Secure verification was not completed. Please try again or use another card.

如果银行卡被拒绝，顾客会看到来自 Culqi 的消息，例如 Payment failed: 后接原因，并可改用其他银行卡重试。如果 Culqi 没有响应，顾客会看到 We could not confirm your payment with Culqi. Please check your email or contact us before trying again. 如果顾客关闭 Culqi 窗口，则不会扣款，顾客会看到 The payment window was closed before the payment was completed.，并可重新下单。

该支付方式适用于经典结账、结账区块和 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。

本插件仅接受银行卡和 Yape 的一次性付款，并立即扣款。不支持 PagoEfectivo 或 CIP 代码、银行应用、代理点、电子钱包或 Cuotéalo，不支持保存银行卡、订阅或分期付款，不使用 Culqi Webhook，也不支持单独的授权和扣款。

订单和退款

订单状态

Pending payment: 订单已创建但尚未扣款，或 Culqi 没有响应。此时备注会显示 Culqi did not confirm the charge。在接受另一笔付款之前，请在 CulqiPanel 中查找该订单的扣款记录。

Processing: 付款已确认（WooCommerce 默认；仅包含可下载虚拟商品的订单会变为「已完成」）。订单备注会显示 Culqi 扣款 ID、模式（测试或正式）以及是否使用了 3-D Secure。交易 ID 即 Culqi 扣款 ID。

On hold: Culqi 报告了金额或币种与订单不符的扣款，或已授权但未扣款的付款。订单备注会对此作出说明并显示扣款 ID。请在 CulqiPanel 中检查该扣款，并手动完成或退款该订单。

Failed: 银行卡被拒绝。订单备注会显示原因、拒绝代码和扣款 ID。顾客可改用其他银行卡再次付款。

已付款或已存在 Culqi 扣款的订单（包括保留状态的订单）绝不会再次扣款。每个订单同一时间只处理一个付款请求。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Culqi。支持全额和部分退款。退款使用付款时所在模式（测试或正式）的密钥发送，即使您此后已切换模式，因此必须设置该模式的私钥。如果 Culqi 不接受退款，WooCommerce 会显示错误，且不会记录任何退款。退款成功后，会将其添加到订单备注中，包含 Culqi 退款 ID、金额和原因。

在 CulqiPanel 中进行的退款不会同步回 WooCommerce。如有需要，请在 WooCommerce 中不使用 Refund via Culqi 手动创建退款。

许可证密钥

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

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

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

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

故障排除

Culqi 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的两个密钥是否都已设置（测试模式下为 Test Public Key 和 Test Secret Key，正式模式下为 Live Public Key 和 Live Secret Key），以及店铺币种是否为 PEN 或 USD。在上述每种情况下，设置页面都会显示警告。

付款已成功，但订单仍为 Pending payment：本插件不使用 Webhook。扣款只能通过 Culqi 向您的服务器返回的响应来确认。如果 Culqi 未及时响应，订单备注会显示 Culqi did not confirm the charge。请在 CulqiPanel 中查找该订单的扣款，如果存在，请手动完成订单。

付款后订单为 On hold：请阅读订单备注。扣款金额或币种与订单不一致，或付款未被扣取。请在 CulqiPanel 中检查该扣款（其 ID 在备注中），然后完成订单或为其退款。

密钥无法保存：错误提示该字段必须以某个前缀开头，例如 sk_live_。每个字段只接受其自身类型和模式的密钥：pk_test_、sk_test_、pk_live_ 或 sk_live_。

顾客看到 Payment gateway misconfiguration. Please contact the store owner.：缺少当前模式的密钥，或 Culqi 拒绝了私钥。请检查设置中的密钥。

顾客看到 Payment token is invalid. Please try again.：来自 Culqi 窗口的令牌属于另一种模式，例如在结账页面打开期间切换了 Test Mode。顾客应重新加载页面并再次付款。

Culqi 窗口无法打开：顾客会看到 The Culqi payment window could not be loaded. Please reload the page and try again. 请检查来自 js.culqi.com 和 3ds.culqi.com 的脚本是否在您的结账页面被屏蔽，例如被优化插件屏蔽。

顾客看到 This order is already being paid：同一订单的另一个付款请求正在同时运行。顾客应等待并查看电子邮件，然后再重试。

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

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

对于开发者，插件文档列出了过滤器 culqi_p_supported_currencies、culqi_p_charge_data、culqi_p_icon 和 culqi_p_lock_timeout。

卸载

停用插件会保留所有数据。如需移除，请在 Plugins 页面停用并删除它。本插件的许可证密钥和许可证状态始终会被移除。仅当 Delete Data on Uninstall 已开启时，才会移除网关设置和日志；否则它们会保留，供以后重新安装时使用。现有订单会保留其付款备注和交易 ID。

Culqi 是其各自所有者的商标。本插件与 Culqi 无关联，也未获得 Culqi 的认可。