VibeFox Culqi for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

店铺货币：秘鲁索尔（PEN）或美元（USD）必须是您店铺已启用的货币。Culqi 不接受其他货币，且只有当顾客使用 PEN 或 USD 付款时，才会显示该付款方式。

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

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

安装

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

OpenCart 3

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

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

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

4. 粘贴集成密钥，正式收款时再粘贴正式密钥（参见配置）。

5. 开启 Enable/Disable 并点击 Save。测试期间保持 Test Mode 开启，正式收款时再关闭。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥和 Culqi 密钥。设置页面及其字段在两个版本中相同。

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在测试模式开启期间，设置上方会显示 Test mode is active: the integration keys are used and no real money is charged. 当网关已启用但当前模式的密钥缺失，或者店铺中没有任何已启用的货币受 Culqi 支持时，页面会发出警告。在这两种情况下，结账时都会隐藏该支付方式。如果您的默认货币不是 PEN 或 USD，页面会提示：只有当顾客使用受支持的货币付款时才会提供 Culqi。若您没有修改扩展的权限，页面可以查看设置，但无法保存。

保存时，错误的值不会被保存，并保留其之前的值，而其他字段则会正常保存。页面会为每个此类字段显示错误：前缀错误的密钥（例如 Live Secret Key must start with sk_live_ — the previous value was kept.）、为空或超过 128 个字符的 Title、不是整数的 Sort Order、不是 0 或更大数字的 Total，以及不存在的地理区域或订单状态。

Culqi

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

Title：顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Credit/Debit Card or Yape (Culqi)。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with your credit/debit card or Yape via Culqi.

Sort Order：Culqi 在结账页支付方式中的排列位置。留空或输入整数。

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

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

API 密钥

从 CulqiPanel > Desarrollo > API Keys 复制密钥：集成（测试）密钥位于 integ-panel.culqi.com，正式密钥位于 mipanel.culqi.com（页面中提供了链接）。测试模式仅使用测试密钥，正式模式仅使用正式密钥。每个密钥都必须以其所在字段的前缀开头。

Test Mode：开启时，使用测试密钥（pk_test_ / sk_test_），不会收取真实款项。默认：开启。关闭后可使用正式密钥收取真实付款。开启期间，顾客在 Confirm Order 步骤会看到 TEST MODE: No real charges will be made.

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

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

Live Public Key：正式环境的公钥。以 pk_live_ 开头。

Live Secret Key：正式环境的私钥。以 sk_live_ 开头，绝不与浏览器共享。

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

支付方式

银行卡始终提供。银行转账、代理、钱包以及 Cuotéalo 需要 Culqi Orders API，本扩展不提供这些方式。

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

订单

OpenCart 会在 Confirm Order 步骤创建没有状态的订单（缺失订单）。只有在 Culqi 确认扣款后，订单才会获得状态。以下每个字段都列出了您 OpenCart 中的订单状态。

Order Status After Payment：Culqi 已确认扣款，且金额和币种与订单一致。默认：Processing。

On Hold (Review) Status：Culqi 扣款的金额或币种与订单不符，或未能完成付款的捕获。备注会说明应在 CulqiPanel 中检查什么。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded Status：付款已在订单页面全额退款。部分退款只会添加备注。默认：Refunded。

高级

Debug log：将 API 请求和付款步骤记录到 OpenCart 日志文件夹（storage/logs）中的 culqi_p_debug.log.php。该文件无法通过网页打开，大小达到 5 MB 时会被移动到 culqi_p_debug.old.log.php。错误（包括银行卡拒付及其代码）始终会被记录。密钥、银行卡数据和顾客信息绝不会被记录。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。Culqi 的扣款和退款记录始终保留，因此即使重新安装后，之前已付款的订单仍可退款。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 Credit/Debit Card or Yape (Culqi)）。在 Confirm Order 步骤中，顾客会看到您的说明，OpenCart 会创建订单，但仍然没有状态。顾客点击 Confirm Order 后，Culqi Checkout 弹窗会在同一页面打开，并显示您的店铺名称、订单总额和货币。顾客在弹窗中输入银行卡信息或使用 Yape 付款。Culqi 脚本始终从 Culqi 加载。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择支付方式，然后点击页面底部确认区块中的 Confirm Order。如果店铺不要求付款地址（OpenCart 4 默认设置），则随扣款发送的顾客信息取自收货地址和顾客姓名。

Culqi 会将付款数据转换为一次性令牌，只有该令牌会发送到您的店铺。您的服务器会通过 Culqi Charges API，以订单货币为订单总额创建扣款，并立即捕获。该扣款会在 CulqiPanel 中显示为 Order，附带订单号和顾客邮箱。只有在 Culqi 确认后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。

如果银行要求进行 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.

如果银行卡被拒付，顾客会在 Payment failed: 之后看到 Culqi 的提示，并可以在同一步骤中使用其他银行卡重试。如果 Culqi 没有响应，顾客会看到 We could not confirm your payment with Culqi. Please check your email or contact us before trying again. 在这些情况下，订单保持无状态，订单记录中的备注会记下本次尝试。如果顾客关闭了 Culqi 窗口，则不会扣款，并且可以再次点击 Confirm Order 按钮。在所有这些情况下，购物车都会被保留。

订单绝不会被重复扣款。如果顾客在同一订单的付款仍在进行时再次提交，顾客会看到 This order is already being paid. Please wait a moment and check your email before trying again. 如果 Culqi 已扣款，但无法设置订单状态，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. 扣款会被保留，使用同一购物车的下一次尝试会根据该扣款设置订单状态，而不会再次扣款。同一购物车只会支付一次：如果同一购物车的另一个订单（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单）已经付款，顾客会被引导至成功页面，且不会再次扣款。OpenCart 4 会在同一结账中保留一个订单并更新它，因此银行卡被拒付后，顾客支付的是同一订单。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单被店铺在此期间关闭（例如已取消或已退款），或者已付款但此后购物车发生了变化（其他商品或数量），Confirm Order 会将顾客带回结账页面，为购物车创建一个带有自己付款的新订单。已付款后又被关闭的订单不再保留购物车。

本扩展仅接受一次性银行卡和 Yape 付款，并立即捕获。不支持银行 App、代理、钱包或 Cuotéalo，不支持保存的银行卡、订阅或分期付款，不支持 Culqi Webhook，也不支持单独的授权和捕获。

订单与退款

订单状态

No status (missing order)：顾客尚未付款、银行卡被拒付，或 Culqi 没有响应。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时，才会显示此类订单。订单历史中的备注会说明失败的尝试。

Order Status After Payment（默认 Processing）：扣款已确认，且与订单相符。备注会显示 Culqi payment successful，包括模式（测试或正式）、是否使用了 3-D Secure，以及 Culqi 扣款 ID（chr_...）。

On Hold (Review) Status（默认 Pending）：Culqi 报告的扣款金额或币种与订单不符，或付款已授权但未捕获。备注会说明原因并显示扣款 ID。请在 CulqiPanel 中检查该扣款，然后完成订单或退款。

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

备注是订单 History 中的条目，顾客看不到。

VibeFox Culqi Payment 选项卡

在 Sales > Orders 中打开一个通过 Culqi 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Culqi Payment 选项卡会显示 Charge ID（测试付款会带有 Test 标签）、已扣款的 Amount（如使用了 3-D Secure 也会显示）、待审核订单的 Review 提示、Paid / refunded 金额、退款表单、退款记录，以及订单的 Culqi notes。该选项卡仅显示给有权访问本扩展的用户。

退款

在 VibeFox Culqi Payment 选项卡中输入 Amount（系统会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Culqi。确认提示 Refund this amount through Culqi? This cannot be undone. 支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 Culqi 实际扣款的金额和货币进行，因此在金额不一致后，您可以退款的上限是顾客实际支付的金额，而不是订单总额。退款会使用付款时所用模式（测试或正式）的密钥发送，即使之后您已切换模式，因此该模式的私钥必须已设置。如果 Culqi 不接受退款，选项卡会显示错误，且不会记录退款。退款成功后，会在退款记录和备注中添加 Culqi 退款 ID、金额以及您填写的原因。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

Sales > Returns 中的商品退货不会通过 Culqi 退还款项。在 CulqiPanel 中进行的退款不会同步回 OpenCart。如有需要，请手动更新订单。

许可证密钥

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

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

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

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

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

故障排除

Culqi 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的两个密钥是否都已设置（测试模式为 Test Public Key 和 Test Secret Key，正式模式为 Live Public Key 和 Live Secret Key），以及顾客是否使用 PEN 或 USD 付款。缺少密钥时，设置页面会显示警告。还请检查付款地址是否位于所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：本扩展不使用 Webhook。扣款只能通过 Culqi 对您服务器的响应来确认。如果 Culqi 未能及时响应，订单会带有 Culqi did not confirm the charge 备注。请在 CulqiPanel 中查找该订单的扣款。如果顾客看到了订单无法完成的提示，同一顾客会话中的下一次付款尝试会在不再次扣款的情况下设置状态。

付款后订单处于审核状态：请阅读 VibeFox Culqi Payment 选项卡中的备注。扣款金额或货币与订单不一致，或付款未被捕获。请在 CulqiPanel 中检查该扣款，然后完成订单或退款。

密钥未能保存：错误信息会提示该字段必须以某个前缀开头，例如 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 的脚本，例如被缓存或优化扩展拦截。

顾客看到 Security check failed. Please reload the page and try again.：结账页面曾在另一个会话中打开。重新加载页面即可解决。

顾客看到 This payment method is not available.：结账会话中已没有 Culqi 订单，或该支付方式在此期间已被关闭。顾客需要重新加载结账页面。

银行卡被拒付，您想了解原因：请查看订单中的备注，或扩展页面上的 Log 字段。即使 Debug log 已关闭，拒付仍会连同 Culqi 拒付代码一起被记录。

选项卡中没有退款表单：选项卡会说明原因：付款已全额退款、您的用户组没有修改扩展的权限，或付款模式的私钥缺失。

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Culqi Payment 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装后，这些设置会恢复为默认值。如果 Delete data on uninstall 已开启，其他网关设置（标题、说明、测试模式、密钥、Yape、日志记录）和日志都会被删除。如果已关闭，则会保留这些设置，供之后重新安装时使用。Culqi 的扣款和退款记录始终会保留，因此即使重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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