VibeFox Kushki for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

货币：USD（厄瓜多尔）或 COP（哥伦比亚）。对于其他货币的订单，结账时不会显示该支付方式。

HTTPS：Kushki 要求在正式模式下通过 HTTPS 提供结账页面。

Kushki 账户：您需要 Kushki 测试（UAT）账户和正式账户的公共和私有 Merchant ID。它们位于 Kushki Console 的 Developers > Credentials 中。对于可选的 Webhook，您还需要每个账户的 Webhook 签名密钥（参见配置）。

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

安装

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

OpenCart 3

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

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

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

4. 输入测试环境的公共和私有 Merchant ID，并保持 Test mode 开启。可选地，在 Kushki Console 中设置 Webhook 并粘贴其签名密钥（参见配置）。

5. 开启 Enable / Disable，点击 Save，然后下一个测试订单。准备就绪后，输入正式环境的 Merchant ID（以及正式环境的 Webhook 签名），并关闭 Test mode。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_kushki_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

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

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

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

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当支付方式已启用但当前模式的 Merchant ID 缺失时（此时该支付方式在结账时会被隐藏）、商店的默认货币不是 USD 或 COP 时、在没有 HTTPS 的情况下使用正式模式时（OpenCart 4 中为商店地址以 http:// 开头时），以及当前模式没有 Webhook 签名密钥时，页面都会向您发出警告。测试模式开启时，页面会显示 Test mode is on: the Kushki test environment is used, no real money is charged. 如果没有修改扩展的权限，页面只显示设置，但无法保存。

保存时，Title 不能为空且不能超过 128 个字符，Sort Order 必须为整数（允许负数），Total 必须是大于或等于 0 的数字，并且每个订单状态都必须存在。如果某个字段有误，则不会保存任何内容，页面会指出该字段。保存时会删除 ID 两侧的空格。

Kushki

Enable / Disable：Enable Kushki card payments 用于开启或关闭该支付方式。默认：关闭。

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

Description：在 Confirm Order 步骤中显示在卡片表单上方的文字。默认：Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

Sort Order：Kushki 在结账时支付方式中的位置。可留空或输入整数。

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

Total：订单必须达到的、以商店默认货币计算的结账金额，达到后才会提供 Kushki。留空则对任何金额都提供 Kushki。

API 凭据

从 Kushki Console（Developers > Credentials；页面中有指向 Console 的链接）复制公共和私有 Merchant ID。测试（UAT）账户和正式账户的 ID 不同。测试模式只使用测试 ID，正式模式只使用正式 ID。

Test mode：使用 Kushki 测试（UAT）环境：测试 Merchant ID、测试卡片表单和测试 API 一起使用。不会扣除真实资金，并且结账时会显示 TEST MODE 标识。默认：开启。关闭它即可接受真实付款。退款始终会退回到付款时所在的环境。

Test Public Merchant ID：您的 Kushki 测试账户的公共 Merchant ID。用于加载卡片表单。

Test Private Merchant ID：您的 Kushki 测试账户的私有 Merchant ID。在服务器上用于扣款和退款。

Live Public Merchant ID：您的 Kushki 正式账户的公共 Merchant ID。

Live Private Merchant ID：您的 Kushki 正式账户的私有 Merchant ID。请妥善保密。

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

Webhook（推荐）

付款会通过 Kushki API 的响应立即确认，因此 Webhook 并非必需。它还可以确认响应丢失（例如超时）的付款，并报告在 Kushki Console 中进行的作废、退款和拒付。在 Kushki Console（Webhooks）中，添加本节 Webhook URL 下显示的 URL。在 OpenCart 3 中它类似于 https://your-store/index.php?route=extension/payment/wcp_kushki_payment/webhook；在 OpenCart 4 中类似于 https://your-store/index.php?route=extension/wcp_kushki_payment/payment/wcp_kushki_payment.webhook，由您的 OpenCart 安装的商店地址生成。请完全按照设置中显示的内容复制 URL。测试账户和正式账户都需要这样做。

该扩展会处理以下卡片通知：

Test webhook signature：Kushki 测试账户的 Webhook 签名密钥（Console > Webhooks）。

Live webhook signature：Kushki 正式账户的 Webhook 签名密钥。

没有有效签名的 Webhook 会被拒绝。通知必须使用付款所在模式的密钥签名，因此测试通知绝不会确认正式付款。如果没有签名密钥，所有 Webhook 通知都会被拒绝，但付款仍然有效，因为它们通过 API 响应确认。

订单

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

Order Status After Payment：Kushki 以订单金额和货币，并附带票号批准了扣款。默认：Processing（处理中）。

On Hold (Review) Status：Kushki 在没有票号的情况下批准了扣款，或者报告了其他金额或货币。备注会说明原因；在发货前请在 Kushki Console 中检查该付款。默认：Pending（待付款），因为 OpenCart 没有“保留”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Status：处于审核状态的订单，其扣款后来被 Kushki 报告为被拒绝（Webhook）。默认：Failed（失败）。

Canceled Status：此状态（或已退款状态）下的订单永远不会因延迟到达的 Webhook 而重新打开。默认：Canceled（已取消）。

Refunded Status：在订单选项卡中对付款进行退款后设置。默认：Refunded（已退款）。

高级

Debug log：将 Kushki 请求和 Webhook 写入 OpenCart 日志文件夹（storage/logs）中的 kushki_p_debug.log.php。该文件无法通过网页打开。警告和错误始终会被记录。日志中绝不包含 Merchant ID、卡片令牌或客户电子邮件。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展会删除设置和日志。Kushki 付款记录（扣款和退款）始终保留，因此重新安装后仍可对旧订单进行退款。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。私有 Merchant ID 和 Webhook 签名不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的机密信息会保留。

结账

在 Payment Method 步骤中，客户选择支付方式（默认为 Credit / debit card (Kushki)）。OpenCart 在 Confirm Order 步骤中创建订单，此时仍无状态。客户在此看到您的说明以及 Kushki 卡片表单，表单中显示以订单货币计算的订单总额。客户输入卡号，如果 Kushki 表单提供分期付款，则选择分期，然后在 Kushki 表单内按下付款按钮。随后付款会自动发送，正如表单下方的提示所说：Enter your card in the secure Kushki form above and press its pay button — the payment is sent automatically. 如果客户改为点击 OpenCart 的 Confirm Order 按钮，则会显示消息 Please enter your card details in the Kushki form and press its pay button.

在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中）。此时 Kushki 银行卡表单会出现在结账页面底部的订单确认区块中，位于 Confirm Order 按钮上方，并且每当 OpenCart 重新加载该区块时，都会按当前订单总额重新生成。

然后您的商店在服务器上扣除卡片费用。只有在 Kushki 以票号确认后，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，购物车被清空，客户会看到 OpenCart 订单成功页面，并显示 Your card payment has been received. Kushki 报告的金额和货币会与订单进行比对。处于审核状态的订单会显示 Your payment is being reviewed. We will update your order as soon as the review is complete.

如果卡片被拒绝，订单保持无状态，客户会停留在 Confirm Order 步骤，并看到 Your payment was declined 以及 Kushki 给出的原因，客户可以在重新加载的表单中尝试其他卡片。如果遇到网络、密钥或服务器问题，客户会看到 The payment could not be processed right now. Please try again in a moment or choose another payment method. 技术原因会写入日志和订单备注。在付款处理过程中再次点击，会显示 A payment for this order is already being processed. Please wait a moment and check your order status.

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会保留并更新结账的订单，但在任一版本中，同一购物车只会被付款一次：已付款的购物车，或订单尚无状态的已批准扣款，永远不会再次被扣款，客户会看到成功页面。如果 Kushki 的响应丢失（例如超时），客户会看到通用消息，但扣款尝试会被保留。当已签名的 Webhook 报告已批准的扣款时，订单会获得状态。如果客户在任何 Webhook 到达之前再次付款，这将是一笔新的扣款；第一笔扣款的延迟批准只会添加一条关于可能重复扣款的备注。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如之后被拒绝的审核中扣款，或您取消了订单），或订单已为之前的购物车付款而客户之后更改了购物车，则客户在付款时会被带回结账页面，下一次 Confirm Order 会创建新订单。订单关闭时，结账页面上方会显示 Your previous order is closed (declined, cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order.；若已为之前的购物车付款，则显示 Your previous order is already paid for other cart contents. Please confirm the order again: the current cart will be paid with a new order. 购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

即使商店处于维护模式，Webhook 也能正常工作：OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展会为其添加一个启动动作。3-D Secure、欺诈规则和提供的分期付款均在 Kushki Console 中设置。

该扩展仅支持一步式卡片付款。不支持部分退款、保存的卡片或订阅，也不支持现金、银行转账（PSE）或借记卡跳转付款，也不支持单独的授权和捕获。

订单与退款

订单状态

无状态（缺失订单）：客户尚未付款，卡片被拒绝，或 Kushki 响应丢失且 Webhook 尚未到达。在 Sales > Orders 中，此类订单仅在筛选器 Order Status 设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：Kushki 已确认扣款（通过 API 响应或 Webhook）。备注会显示模式、金额、Kushki 票号和参考号。

On Hold (Review) Status（默认 Pending）：Kushki 返回了成功但没有票号，或报告的金额或货币与订单不同。备注会解释原因。请在 Kushki Console 中检查该交易，然后处理订单或退还付款。之后带有票号和匹配金额的已签名批准，会将订单设为 Order Status After Payment。

Failed Status（默认 Failed）：Webhook 报告处于审核状态的订单的扣款已被拒绝。

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

如果 Kushki 为已付款、已取消或已退款的订单报告了另一笔已批准的扣款，订单不会被更改。备注会提示您检查是否重复扣款，并在 Kushki Console 中将其退款。来自测试环境、针对正式付款的 Webhook（反之亦然）会被忽略，并附带备注。

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

VibeFox Kushki Payment 选项卡

在 Sales > Orders 中打开使用 Kushki 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Kushki Payment 选项卡会显示 Ticket number（测试付款带有 TEST 标签）、Transaction reference、Environment、Result、Charged / order amount 金额、退款表单、退款历史以及订单的 Kushki notes。该选项卡对有权访问该扩展的用户显示。

退款

Kushki 会全额退还扣款，因此只能进行全额退款。在 VibeFox Kushki Payment 选项卡中，会填入 Kushki 扣除的 Amount。可选填写 Reason (optional)，点击 Refund via Kushki，然后确认问题 Refund the full payment through Kushki? This cannot be undone. 您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。对于任何其他金额，扩展会显示 Kushki refunds the full payment only. Enter the full charged amount 及该金额，并且不会发送任何内容。退款以 Kushki 扣除的金额和货币进行，因此在金额不一致后，客户取回的是实际扣除的金额，而不是订单总额。同一付款只能退款一次。

退款会在付款所用的模式（测试或正式）中发送，因此该模式的私有 Merchant ID 必须已设置。如果 Kushki 不接受退款，选项卡会显示 Kushki refund failed 以及 Kushki 的错误代码和消息，并且不会记录任何退款。成功的退款会添加到退款历史和备注中，并附上 Kushki 退款票号，订单会设为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态时一样。退款需要已确认且带有票号的 Kushki 扣款。

Sales > Returns 中的商品退货不会通过 Kushki 退回款项。在 Kushki Console 中进行的作废和退款会通过 Webhook 到达，并添加到备注中。订单状态不会自动改变。

许可证密钥

该扩展需要使用从 vibefox.net 获得的 VibeFox 许可证密钥。许可证区块 License — VibeFox Kushki Payment 位于 Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店移除密钥）。其下方是行 Product: opencart-payment-kushki 以及链接 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 账户中释放该名额。

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

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

故障排除

Kushki 未在结账时显示：检查许可证是否有效、Enable / Disable 是否开启，以及当前模式是否同时具有两个 Merchant ID：测试模式使用测试 ID，正式模式使用正式 ID。缺少 ID 时，设置页面会显示警告。检查订单货币是否为 USD 或 COP，付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Kushki API 的响应丢失，例如因超时。Webhook 会确认此类付款。在 Kushki Console 中，检查 Webhook URL 是否与 Webhook URL 中显示的完全一致，并且针对您所用模式的账户，该账户的签名密钥是否位于对应字段（Test webhook signature 或 Live webhook signature）中。付款金额和货币不符的已批准扣款会使订单进入 On Hold (Review) Status。

Webhook 返回 Webhook signature not configured：未设置任何 Webhook 签名。请将签名密钥粘贴到设置中。

Webhook 返回 Invalid signature：签名密钥属于其他账户或模式，或者通知在传输过程中被修改。

Webhook 返回 Order mismatch：该通知不属于此订单的扣款尝试（尝试密钥或交易错误）。不会做任何更改。

Webhook 返回 Busy, retry later：订单在同一时刻正被另一请求处理，或无法设置订单状态。Kushki 可能会重新发送通知。错误始终会写入日志。

Webhook URL 在浏览器中仅显示 POST：这是正常的。该 URL 只接受来自 Kushki 的通知。

卡片表单无法加载：客户会看到 The Kushki card form could not be loaded. Please reload the page or choose another payment method. 请检查当前模式的公共 Merchant ID。

客户看到 This payment option is not available in this store. Please pay by card.：在 Kushki 表单中选择了非卡片付款选项。该扩展仅对卡片扣款。

客户付款时看到错误：开启 Debug log，并查看扩展页面上的 Log 字段。This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不匹配，或支付方式在此期间已被关闭：客户需要重新加载结账页面。错误或缺失的私有 Merchant ID 会显示付款无法处理的通用消息。

客户看到 Your payment was received, but the order could not be completed automatically：Kushki 已批准扣款，但 OpenCart 无法设置订单状态。日志会显示原因。同一购物车的下一次付款尝试会在不重新扣款的情况下设置状态。

退款因与模式相关的消息而失败：付款是在测试或正式模式下进行的，而该模式的私有 Merchant ID 未设置。请输入后重试。

选项卡中没有退款表单：选项卡会说明原因：付款已退款，订单没有 Kushki 票号（No Kushki ticket number found for this order — refund it in the Kushki Console.），您的用户组没有修改该扩展的权限，或付款模式的私有 Merchant ID 未设置。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Kushki Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，这些设置在重新安装后会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件（含显示结账页面上方消息的事件）和启动动作，该动作在维护模式下允许 Webhook 通过）。如果 Delete data on uninstall 已开启，其他设置（标题、描述、测试模式、Merchant ID、Webhook 签名、日志记录）和日志也会被删除。如果已关闭，则会保留，以便日后重新安装时使用。Kushki 付款记录（扣款和退款）始终会保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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