VibeFox Kushki for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装时插件无法激活。

PHP：8.0 或更高版本。

商店货币：USD（厄瓜多尔）或 COP（哥伦比亚）。使用其他货币时，结账时会隐藏该付款方式。

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

Kushki 账户：您需要 Kushki 测试（UAT）账户和正式账户的 Public 与 Private Merchant ID。它们位于 Kushki Console 的 Developers > Credentials 中。若要使用可选的 Webhook，您还需要每个账户的 Webhook 签名密钥（参见配置）。

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

安装

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

2. 点击 Activate。

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

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

5. 输入测试的 Public 和 Private Merchant ID，并保持 Test mode 开启。可选：在 Kushki Console 中设置 Webhook 并粘贴其签名密钥（参见配置）。

6. 开启 Enable / Disable 并进行一次测试下单。准备就绪后，输入正式的 Merchant ID（以及正式的 Webhook 签名），并取消勾选 Test mode。

配置

所有设置都在一个页面中：WooCommerce > Settings > Payments > Kushki。在字段上方，如果付款方式已启用但当前模式的 Merchant ID 缺失（此时该付款方式会在结账时隐藏）、商店货币不受支持、在未使用 HTTPS 的情况下使用正式模式，或当前模式没有 Webhook 签名，页面会显示警告。测试模式开启时，页面会显示 Test mode is on: the Kushki test environment is used, no real money is charged. 如果在付款方式已启用、但未填写当前模式 Merchant ID 的情况下保存，会出现错误提示提醒您填写。保存时会删除 ID 前后的空格。

常规

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

Title: 顾客在结账时看到的付款方式名称。默认：Credit / debit card (Kushki)。

Description: 结账时银行卡表单上方显示的文字。默认：Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

API 凭据

从 Kushki Console（Developers > Credentials）复制 Public 和 Private Merchant ID。测试（UAT）账户和正式账户的 ID 不同。测试模式只使用测试 ID，正式模式只使用正式 ID。

Test mode: Use the Kushki test (UAT) environment 会同时将 Merchant ID、银行卡表单和 API 切换到 Kushki 测试环境。不会扣除真实款项，结账时会显示 TEST MODE 标记。默认：开启。取消勾选即可接受真实付款。

Test Public Merchant ID: 您的 Kushki 测试账户的 Public Merchant ID。用于加载银行卡表单。

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

Live Public Merchant ID: 您的 Kushki 正式账户的 Public Merchant ID。

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

Webhook（推荐）

付款会立即由 Kushki API 响应确认，因此 Webhook 并非必需。它还会确认响应丢失的付款（例如超时），并报告在 Kushki Console 中进行的作废和退款。在 Kushki Console（Webhooks）中，添加设置中此部分显示的 URL，用于银行卡付款。格式类似：https://your-site/wc-api/webhook_kushki_p/。测试账户和正式账户都需要添加。

插件会处理以下银行卡通知：

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

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

签名无效的 Webhook 会被拒绝。没有签名密钥时，所有 Webhook 通知都会被拒绝，但付款仍然正常，因为它们由 API 响应确认。

高级

Debug log: Log API calls and webhooks 会将 Kushki 请求和 Webhook 写入 WooCommerce > Status > Logs，来源为 wcp_kushki_payment。错误始终会被记录。日志从不包含 Merchant ID、卡令牌或顾客邮箱。默认：关闭。

Delete data on uninstall: 开启后，删除插件会移除设置和日志。订单及其 Kushki 参考信息会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Credit / debit card (Kushki)）。Kushki 银行卡表单会显示在其下方，并以订单货币显示订单总额。在 Pay for order 页面，表单使用订单总额。顾客输入银行卡信息，如果 Kushki 表单提供分期选项则选择分期，然后点击 Kushki 表单内的付款按钮。

在经典结账中，选择 Kushki 时会隐藏 WooCommerce 的 Place order 按钮：银行卡被接受后，订单会自动提交。在结账区块中，顾客同样需要点击 Kushki 表单内的付款按钮。如果顾客未这样做就尝试下单，会显示提示 Please enter your card details in the Kushki form and press its pay button.

随后，您的商店在服务器端扣款。只有在 Kushki 以票据号确认后，订单才会被标记为已付款，顾客会直接进入订单完成页面。如果 Kushki 报告了已批准的金额或币种，会与订单进行比对。

如果银行卡被拒绝，顾客会看到 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.

该付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。3-D Secure、欺诈规则和提供的分期选项需在 Kushki Console 中设置。

插件仅支持一步完成的银行卡付款。不支持部分退款、保存的银行卡、订阅或 Add payment method，不支持现金、银行转账（PSE）或借记卡跳转付款，也不支持单独授权和扣款。

订单与退款

订单状态

Pending payment: 订单已创建，银行卡尚未扣款。

Processing: Kushki 已确认扣款（通过 API 响应或 Webhook）。仅包含虚拟可下载商品的订单会变为 WooCommerce 默认的 Completed。订单备注会显示模式、Kushki 票据号和参考号。交易 ID 为 Kushki 交易参考号（或票据号）。

On hold: Kushki 返回了成功但没有票据号，或报告的金额或币种与订单不符。订单备注会说明原因。请在 Kushki Console 中核实交易，然后完成订单或退还款项。

Failed: 银行卡被拒绝或无法完成扣款。订单备注会显示 Kushki 的代码和消息。顾客可以重新付款。

如果 Webhook 报告已付款、已取消或已退款的订单又有一笔已批准的扣款，订单不会被修改。备注会提醒您检查是否重复扣款，并在 Kushki Console 中退款。正式订单收到测试环境的 Webhook（反之亦然）时，会被忽略并附上备注。

退款

打开订单，点击 Refund，输入完整的订单总额，然后点击 Refund via Credit / debit card (Kushki)（按钮上会显示您的 Title）。Kushki 会退还整笔付款，因此只接受全额退款。若输入部分金额，插件会显示 Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. 每笔付款只能退款一次。

退款会以付款时所用的模式（测试或正式）发送，因此必须已设置该模式的 Private Merchant ID。如果 Kushki 不接受退款，WooCommerce 会显示错误，且不会记录退款。成功的退款会连同 Kushki 退款票据一起添加到订单备注中。

在 Kushki Console 中进行的作废和退款通过 Webhook 送达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。

许可证密钥

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

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

没有有效密钥时，结账时不会向顾客显示 Kushki。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的商店管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：Webhook 仍会被处理，退款也可以正常进行。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时没有显示 Kushki：检查许可证是否有效，Enable / Disable 是否开启，以及当前模式是否同时具有两个 Merchant ID：测试模式使用测试 ID，正式模式使用正式 ID。检查商店货币（或 Pay for order 页面上的订单货币）是否为 USD 或 COP。设置页面会针对上述每个问题显示警告。

付款已完成，但订单为 Failed 或仍为 Pending payment：Kushki API 响应丢失，例如因超时。Webhook 会确认此类付款。请在 Kushki Console 中检查 Webhook URL 是否与设置中显示的完全一致，是否针对您所用模式的账户，以及该账户的签名密钥是否填在对应字段中（Test webhook signature 或 Live webhook signature）。如果已批准的扣款缺少已付金额和币种，订单会改为“保留”状态。

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

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

Webhook 返回 Order mismatch：该通知不属于此订单（订单密钥或交易有误）。订单不会被修改。

Webhook 返回 Busy, retry later：订单同时正在被另一个请求处理。Kushki 可能会重新发送该通知。

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

顾客看到 This payment option is not available in this store. Please pay by card.：在 Kushki 表单中选择了非银行卡的付款选项。插件只接受银行卡。

顾客付款时出现错误：打开订单备注，或开启 Debug log 并查看 WooCommerce > Status > Logs，来源为 wcp_kushki_payment。错误或缺失的 Private Merchant ID 会给出付款无法处理的通用消息。

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

退款失败并提示 No Kushki ticket number found for this order：该订单没有已确认的 Kushki 扣款。请在 Kushki Console 中退款。

其他货币：开发者可以通过 kushki_p_supported_currencies 过滤器修改货币列表，风险自负。该货币必须已在您的 Kushki 账户中启用。

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

卸载

停用插件会保留所有数据。要删除插件，请在 Plugins 页面将其停用并删除。该插件的许可证密钥和许可证状态始终会被删除。仅当 Delete data on uninstall 已开启时，付款方式设置和日志才会被删除；否则它们会保留，以便之后重新安装。现有订单会保留其付款备注、Kushki 票据号和交易 ID。

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