VibeFox Kushki for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。

币种：USD（厄瓜多尔）或 COP（哥伦比亚）。对于其他币种的购物车，结账时会隐藏该付款方式。

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

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

VibeFox license key：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Kushki Payment，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段并点击 Activate（参见许可证密钥）。

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

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

安装时，模块会创建订单状态 Kushki payment on hold。PrestaShop 会将新的付款模块分配给您商店的币种、国家和客户组。在 Payment > Preferences 中，请确认该模块已对 USD 或 COP 以及厄瓜多尔或哥伦比亚开放。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Kushki Payment > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，当付款方式已启用但当前模式的 Merchant ID 缺失时（此时付款方式会在结账页面隐藏）、商店的默认币种不是 USD 或 COP 时、在没有 HTTPS 的情况下使用正式模式时，以及当前模式没有 Webhook 签名时，页面都会发出警告。在测试模式开启期间，页面会显示 测试模式已开启：使用 Kushki 测试环境，不会扣除真实款项。 如果您在付款方式已启用但未填写当前模式 Merchant ID 的情况下保存，设置仍会被保存，并会有一条消息提醒您填写。保存时会删除 ID 前后的空格。

Kushki

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：使用 Kushki 测试（UAT）环境：测试 Merchant ID、测试卡表单和测试 API 同时生效。不会扣除真实款项，结账时会显示 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。请妥善保密。

已保存的 Private Merchant ID 和 Webhook 签名不会再次显示。该字段会保持为空，并显示 已保存：留空即可保持不变。 只有在需要更改时才输入新值。

Webhook（推荐）

付款会立即通过 Kushki API 响应确认，因此 Webhook 并非必需。此外，它还会为响应丢失的付款（例如超时）创建订单，并报告在 Kushki Console 中进行的作废和退款。在 Kushki Console（Webhooks）中，为银行卡付款添加 Webhook URL 中显示的 URL。启用友好 URL 时，它的形式为 https://your-shop/module/wcp_kushki_payment/webhook，前面可能带有语言代码，如 /es/。请完全按照设置中显示的内容复制该 URL。测试账户和正式账户都要这样做。

模块处理以下银行卡通知：

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

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

Clear saved secrets：勾选某个 Private Merchant ID 或 Webhook 签名，然后点击 Save 将其删除。空字段会保留已保存的值。

没有有效签名的 Webhook 会被拒绝。通知必须使用付款时所用模式的密钥签名，因此测试通知永远不会确认真实付款。如果没有签名密钥，所有 Webhook 通知都会被拒绝，但付款仍可正常进行，因为它们由 API 响应确认。

高级

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

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

Delete data on uninstall：开启时，卸载模块会删除设置和日志。Kushki 付款记录（扣款和退款）以及订单状态 Kushki payment on hold 始终会保留，以便旧订单在重新安装后仍可退款。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Credit / debit card (Kushki)）。其下方会出现 Kushki 卡表单，并以购物车币种显示购物车总额。顾客输入卡信息，如果 Kushki 表单提供分期付款，则选择分期，然后点击 Kushki 表单内的付款按钮。

PrestaShop 的 Place order 按钮会保持可见，因为它包含服务条款。如果已接受条款，则付款会在 Kushki 付款按钮之后自动提交。否则，顾客会看到 Kushki 已接受您的银行卡。请接受服务条款，然后点击“Place order”进行付款。 如果顾客在未使用 Kushki 表单的情况下点击 Place order，则会显示 请在 Kushki 表单中输入您的银行卡信息，然后点击其付款按钮。 消息。

随后，您的商店在服务器端扣除该卡的款项。只有在 Kushki 以票据号确认后，订单才会被标记为已付款。然后订单被创建，顾客会看到标准的订单确认页面，并显示 您的银行卡付款已收到。 如果 Kushki 报告了已批准的金额或币种，会将其与购物车进行比较。保留中的订单会显示 您的付款正在审核中。审核完成后，我们会尽快更新您的订单。

如果银行卡被拒绝，则不会创建订单，顾客会返回付款步骤，并看到 您的付款被拒绝 以及 Kushki 给出的原因，之后可以尝试其他银行卡。对于网络、密钥或服务器问题，顾客会看到 目前无法处理付款。请稍后再试，或选择其他付款方式。 技术原因会写入日志。在付款处理过程中再次点击，会显示 此订单的付款正在处理中。请稍候并检查您的订单状态。

如果 Kushki 的响应丢失（例如超时），顾客会看到通用消息，但扣款尝试会被保留。当签名的 Webhook 报告扣款已批准时，将创建订单。已经有订单的购物车，或者已批准但订单尚未创建的扣款，绝不会被再次扣款：顾客会看到该订单的确认。如果顾客在任何 Webhook 到达之前再次付款，这将是一次新的扣款；第一次扣款的延迟批准只会添加一条关于可能重复扣款的备注。

即使商店处于维护模式，Webhook 仍然有效，并且不会受到商店国家限制的阻止。3-D Secure、欺诈规则以及提供的分期选项都在 Kushki Console 中设置。

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

订单和退款

订单状态

No order yet：顾客尚未付款，银行卡被拒绝，或者 Kushki 响应丢失且 Webhook 尚未到达。此时只存在购物车。

Payment accepted：Kushki 已确认扣款（通过 API 响应或 Webhook）。付款会以 Kushki 交易参考号（或票据号）作为交易 ID 记录。备注会显示模式、Kushki 票据号和参考号。

Kushki payment on hold：Kushki 返回了成功但没有票据号，或报告的金额或币种与购物车不同，或者付款期间购物车被修改。备注会说明原因。请在 Kushki Console 中检查该交易，然后处理订单或退款。之后带有票据号和匹配金额的已签名批准会将订单设为 Payment accepted。

Payment error：Webhook 报告某个保留订单的扣款被拒绝。

Refunded：该付款已通过模块退款。

如果 Kushki 报告某个已付款、已取消或已退款的订单又有另一笔已批准的扣款，订单不会被修改。备注会要求您检查是否存在重复扣款，并在 Kushki Console 中退款。来自测试环境、针对正式付款的 Webhook（或反之）会被忽略，并附上备注。

Kushki 付款区块

订单页面会显示一个 Kushki payment 区块，其中包含票据号、交易参考号、环境（测试付款会显示 Test 标识）、扣款状态、已扣金额和订单总额、退款表单、退款历史，以及该订单的 Kushki notes。

退款

Kushki 会退还整笔扣款，因此只能进行全额退款。在 Kushki payment 区块中，已填入 Kushki 扣除的金额。您可以选择填写原因，然后点击 Refund via Kushki，再确认问题 通过 Kushki 退还全部付款？此操作无法撤销。 您需要拥有编辑订单的权限。对于任何其他金额，模块会在该金额旁显示 Kushki 仅退还全部付款。请输入全部扣款金额，并且不会发送任何内容。退款以 Kushki 扣除的金额和币种进行，因此在金额不一致的情况下，顾客取回的是实际扣除的金额，而不是订单总额。同一笔付款只能退款一次。

退款会以付款时所用的模式（测试或正式）发送，因此必须设置该模式的 Private Merchant ID。如果 Kushki 不接受退款，该区块会显示 Kushki 退款失败，并附上 Kushki 的代码和消息，且不会记录任何退款。成功的退款会以 Kushki 退款票据添加到退款历史和备注中，订单状态设为 Refunded。退款需要已确认且带有票据号的 Kushki 扣款。

模块不会创建贷项单。订单页面上 PrestaShop 的标准退款按钮不会通过 Kushki 退款。在 Kushki Console 中进行的作废和退款会通过 Webhook 到达，并添加到备注中。订单状态不会自动更改。

许可证密钥

模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Kushki Payment 许可证区块是 Modules > Module Manager > VibeFox Kushki Payment > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中删除该密钥。其下方有一行 Product: presta-payment-kushki 和链接 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 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Kushki。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该支付方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。

许可证过期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Kushki：请检查许可证是否有效、Enable / Disable 是否开启，以及当前模式是否同时具有两个 Merchant ID：测试模式需要测试 ID，正式模式需要正式 ID。检查购物车币种是否为 USD 或 COP。在 Payment > Preferences 中，检查模块是否允许该购物车币种、顾客所在国家以及顾客所在客户组。缺少 ID 时，设置页面会显示警告。

付款已完成，但未创建订单：Kushki API 响应丢失，例如因超时。Webhook 会为这类付款创建订单。请在 Kushki Console 中检查 Webhook URL 是否与 Webhook URL 中显示的完全一致，并且对应您所用模式的账户，同时该账户的签名密钥是否位于对应字段（Test webhook signature 或 Live webhook signature）中。缺少已付金额和币种的已批准扣款，会将订单创建在 Kushki payment on hold 中。

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

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

Webhook 返回 Order mismatch：该通知不属于此购物车的任何扣款（尝试密钥或交易不正确）。不会做任何更改。

Webhook 返回 Busy, retry later：订单在同一时刻正被另一个请求处理，或者订单无法创建（例如模块已禁用）。Kushki 可能会再次发送该通知。错误始终会写入日志。

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

银行卡表单无法加载：顾客会看到 无法加载 Kushki 银行卡表单。请重新加载页面或选择其他付款方式。 请检查当前模式的 Public Merchant ID。

顾客看到 此付款方式在本商店不可用。请使用银行卡付款。：在 Kushki 表单中选择了非银行卡的付款方式。模块只收取银行卡款项。

顾客在付款时看到错误：请开启 Debug log，然后查看模块页面上的 Log 字段。错误或缺失的 Private Merchant ID 会导致通用的付款无法处理消息。

顾客看到 您的付款已收到，但订单无法自动完成：Kushki 已批准扣款，但 PrestaShop 无法创建订单。日志会显示原因。同一购物车的下一次付款尝试会创建订单，而不会再次扣款。

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

退款未提供，并显示“未找到此订单的 Kushki 票据号”：该订单没有已确认的 Kushki 扣款。请在 Kushki Console 中退款。

卸载

进入 Modules > Module Manager，打开 VibeFox Kushki Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Kushki 付款记录（扣款和退款）以及订单状态 Kushki payment on hold 始终会保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注、Kushki 票据号和交易 ID。

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