VibeFox Culqi for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
店铺币种：秘鲁索尔（PEN）或美元（USD）。Culqi 不接受其他币种，且只有 PEN 或 USD 的购物车才会显示该付款方式。
Culqi 账户：您需要 Culqi 账户的公钥和私钥。集成（测试）密钥可从 integ-panel.culqi.com 获取，正式（live）密钥可从 mipanel.culqi.com 获取，位置均为 CulqiPanel > Desarrollo > API Keys。公钥由浏览器中的 Culqi 弹出窗口使用。私钥仅在您的服务器上使用，绝不会发送到浏览器。无需配置 Webhook。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Culqi Payment，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见「许可证密钥」）。
4. 粘贴集成密钥；如需真实收款，再粘贴正式密钥（参见「配置」）。
5. 开启 Enable/Disable 并点击 Save。测试期间保持 Test Mode 开启，测试完成后关闭以接收真实付款。
6. 确认 PEN 或 USD 是您店铺已启用的币种。
安装时，模块会创建订单状态 Culqi payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的支付模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Culqi Payment > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。测试模式开启时，页面在字段上方显示 Test mode is active: the integration keys are used and no real money is charged.。当网关已启用但当前模式的密钥缺失，或店铺中没有任何币种受 Culqi 支持时，页面会发出警告。这两种情况下，结账时都会隐藏该付款方式。如果您的默认币种不是 PEN 或 USD，页面会提示 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。测试模式只使用测试密钥，正式模式只使用正式密钥。每个密钥都必须以其所在字段的前缀开头。前缀错误的密钥不会被保存：页面会显示错误，例如 Live Secret Key must start with sk_live_ — the previous value was kept.，其他字段仍会保存。
Test Mode：开启时使用测试密钥（pk_test_ / sk_test_），不会扣除任何真实款项。默认：开启。关闭后，将使用正式密钥接收真实付款。开启期间，顾客会在付款方式下方看到 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 saved secret keys：勾选 Test Secret Key 或 Live Secret Key，然后点击 Save 即可删除。留空字段则保留已保存的值。
付款方式
始终提供银行卡。银行转账、代理点、电子钱包和 Cuotéalo 需要 Culqi Orders API，本模块不提供。
Yape：Offer Yape in the Culqi popup 会在 Culqi 窗口中于银行卡旁显示 Yape。默认：开启。
高级
Debug log：将 API 请求和付款步骤记录到模块文件夹中的 logs/culqi_p_debug.log.php。该文件无法通过网页打开。错误（包括银行卡拒绝及其代码）始终会被记录。密钥、银行卡数据和顾客信息绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete Data on Uninstall：开启后，卸载模块会删除网关设置、模块的 Culqi 扣款和退款记录以及日志。订单状态和订单中的 Culqi 数据（付款、备注）始终保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 Credit/Debit Card or Yape (Culqi)），然后点击下单按钮。Culqi Checkout 弹出窗口会在同一页面打开，显示您的店铺名称、购物车总额和币种。顾客在窗口中输入银行卡信息或使用 Yape 付款。Culqi 脚本仅在结账页面加载。
Culqi 会将付款数据转换为一次性令牌，并将令牌发送至您的店铺。您的服务器通过 Culqi Charges API 按购物车币种创建购物车总额的扣款，并立即完成扣款。该扣款会在 CulqiPanel 中显示为 Cart 和购物车编号，并附带顾客的电子邮件。在此之前不存在任何订单。只有在 Culqi 确认后，订单才会被标记为已付款：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. 并可以重新下单。在上述所有情况下，购物车都会保留。由于尚未生成订单，失败的尝试会记录在模块日志中。
购物车绝不会被扣款两次。如果顾客在同一购物车的付款仍在处理时再次提交，会看到 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. 扣款会被保留，下一次尝试将基于该扣款创建订单，不会再次扣款。
本模块仅接受银行卡和 Yape 的一次性付款，并立即完成扣款。不支持 PagoEfectivo 或 CIP 代码、银行应用、代理点、电子钱包或 Cuotéalo，不支持保存银行卡、订阅或分期付款，不使用 Culqi Webhook，也不支持单独的授权和扣款。
订单和退款
订单状态
No order yet：银行卡被拒绝、顾客关闭了 Culqi 窗口，或 Culqi 没有响应。此时只存在购物车。详细信息见模块日志。
Payment accepted：扣款已确认且与购物车一致。付款会以 Culqi 扣款 ID（chr_...）作为交易 ID 记录，备注会显示模式（测试或正式）以及是否使用了 3-D Secure。
Culqi payment on hold：Culqi 报告的扣款金额或币种与购物车不符，或付款已授权但未完成扣款。备注会说明原因并显示扣款 ID。以购物车币种完成的扣款会记录为按实际扣款金额计入的付款。请在 CulqiPanel 中核实该扣款，然后处理订单或退还付款。
Refunded：该付款已通过模块全额退款。
如果同一购物车已有订单，又收到第二笔扣款，订单不会被修改。备注会提醒您在 CulqiPanel 中核实该扣款，并在需要时予以退款。
Culqi payment 区块
订单页面会显示 Culqi payment 区块，其中包括扣款 ID、扣款金额（如使用了 3-D Secure，则会注明）、测试付款的 Test 标记、保留订单的核查提示、已付和已退金额，以及退款记录。
退款
在 Culqi payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Culqi。确认提示 Refund this amount through Culqi? This cannot be undone. 支持全额和部分退款。您需要具备编辑订单的权限；无需模块访问权限。退款以 Culqi 实际扣款的金额和币种进行，因此在出现金额不一致后，您最多只能退还顾客实际支付的金额，而非订单总额。退款会使用付款时所在模式（测试或正式）的密钥发送，即使之后您已切换模式，因此该模式的私钥必须已设置。如果 Culqi 不接受退款，区块会显示错误，且不会记录任何退款。退款成功后，会将 Culqi 退款 ID、金额和您填写的原因添加到退款记录和订单备注中。全额退款会将订单设为 Refunded。部分退款不会改变订单状态。
本模块不会生成 credit slip（退款单）。订单页面上标准的 PrestaShop 退款按钮不会通过 Culqi 退款。在 CulqiPanel 中进行的退款不会同步回 PrestaShop。如有需要，请手动更新订单。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Culqi Payment 位于 Modules > Module Manager > VibeFox Culqi Payment > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示已打码的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于将该密钥从本店铺中移除。其下方有一行 Product: presta-payment-culqi 和链接 Manage licenses and domains in your account，点击即可打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工可以更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Culqi。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 前台店铺无法识别您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。已有订单不受影响：已发起的付款仍会被确认，退款也照常进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 Culqi：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的两个密钥是否都已设置（测试模式为 Test Public Key 和 Test Secret Key，正式模式为 Live Public Key 和 Live Secret Key），以及购物车币种是否为 PEN 或 USD。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属群组。
付款已完成，但未生成订单：模块不使用 Webhook。扣款仅通过 Culqi 对您服务器的响应确认。如果 Culqi 未及时响应，模块日志会显示 Culqi did not confirm the charge 及购物车编号。请使用此 cart_id 在 CulqiPanel 中查找该扣款。如果顾客看到了订单无法完成的消息，同一购物车的下一次付款尝试会在不再次扣款的情况下创建订单。
付款后订单处于 Culqi payment 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 的脚本，例如缓存或优化模块可能造成阻止。
顾客看到：Security check failed. Please reload the page and try again.:结账页面打开的时间过长，或在另一个会话中打开。重新加载页面即可解决。
顾客看到：This order is already being paid:同一购物车的另一个付款请求恰好同时在进行。顾客应等待并查看电子邮件后再重试。
银行卡被拒绝，您想了解原因：请查看模块页面上的 Log 字段。即使 Debug log 已关闭，拒绝记录也会包含 Culqi 的拒绝代码。
退款因密钥相关消息失败：付款是在测试或正式模式下完成的，而该模式的私钥未设置。请输入私钥后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox Culqi Payment 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置、模块的 Culqi 扣款和退款记录以及日志都会被删除。此后，之前已付款的订单将无法再通过订单页面退款。如果该选项关闭，所有数据都会保留，以便日后重新安装。订单状态 Culqi payment on hold 始终保留。现有订单会保留其付款备注和交易 ID。
Culqi 是其各自所有者的商标。本模块与 Culqi 无关联，也未获得 Culqi 的认可。