VibeFox Paystack for PrestaShop — 帮助

要求

PrestaShop：8.0 至 9.x。

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

货币：购物车必须使用 Paystack 支持的货币：NGN、USD、GHS、ZAR、KES、XOF、EGP 或 RWF，且须已在您的 Paystack 账户中启用。使用其他货币时，付款方式会被隐藏。在 XOF 和 RWF 中，Paystack 仅接受整数金额。

Paystack 账户：您需要 Paystack 账户的密钥：测试密钥（sk_test_...）和/或正式密钥（sk_live_...）。由于付款在 Paystack 托管页面上完成，因此不需要公钥（pk_...）。您还需要在 Paystack 后台设置商店的 Webhook URL（参见配置）。您的商店必须能从互联网访问，才能接收 Webhook。

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

安装

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

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

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

4. 从 Paystack 后台粘贴您的密钥，并在 Paystack 后台设置 Webhook URL（参见配置）。

5. 开启 Enable/Disable，然后点击 Save。在完成一次测试付款之前，请保持 Test Mode 开启；之后关闭它即可接受真实付款。

安装时，模块会创建两个订单状态：Awaiting Paystack payment 和 Paystack payment on hold。PrestaShop 会为所有货币、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中对其进行限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Paystack Payment > Configure。每个包含字段的部分都有自己的 Save 按钮，该按钮会保存整个页面。字段上方的状态框会显示模式：测试模式：不会扣除真实款项。 或 正式模式：将接受真实付款。 当前模式的密钥为空、在密钥字段中填入了公钥（pk_...）、正式模式中使用了测试密钥（sk_test_...）或测试模式中使用了正式密钥（sk_live_...）、以及 Paystack 不接受商店默认货币时，它也会发出警告。只要存在密钥问题，结账时就会隐藏付款方式。

Paystack

第一个部分标题为 Paystack，并带有当前模式的 TEST 或 LIVE 标识。

Enable/Disable：Enable Paystack Payment 用于开启或关闭该付款方式。默认：关闭。

Title：客户在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Paystack。必填。

Description：结账时显示在付款方式下方的文字。默认：Pay securely using your debit card, credit card, or bank account via Paystack.

API 密钥

从 Paystack 后台的 Settings > API Keys & Webhooks 页面复制密钥。该部分包含指向此页面的链接。

Test Mode：新付款使用测试密钥，不会扣除真实款项。关闭后，将使用正式密钥接受真实付款。在另一种模式下完成的付款，在验证和退款时仍会使用其所属模式的密钥。默认：开启。开启时，客户会在付款方式下方看到 测试模式已启用。不会产生任何真实扣款。

Test Secret Key：您的 Paystack 测试密钥。以 sk_test_ 开头。

Live Secret Key：您的 Paystack 正式密钥。以 sk_live_ 开头。

已保存的密钥不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。

Clear saved secrets：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。

Webhook

即使客户没有返回商店，Webhook 也会告知您的商店付款已完成。在 Paystack 后台的 Settings > API Keys & Webhooks 页面中，将本部分 Webhook URL 中显示的网址同时设置为 Test Webhook URL 和 Live Webhook URL。启用友好网址后，它的形式类似 https://your-shop/module/wcp_paystack_payment/webhook，可能还会带有语言代码，例如 /en/。请完全按照设置中显示的网址进行复制。

Paystack 使用您的密钥对每个 Webhook 进行签名，因此无需配置其他内容。签名无效的 Webhook 会被拒绝。模块使用 charge.success 事件：

其他事件会返回 OK 并被忽略。如果没有 Webhook，只有在客户付款后返回商店时，订单才会被确认。稍后完成的银行转账和 USSD 付款仅通过 Webhook 确认。

订单

Autocomplete Order：开启后，已付款订单会获得 Delivered 状态，而不是 Payment accepted，且只进行一次状态变更。默认：关闭。

高级

Debug log：将 Paystack 事件和 API 调用记录到模块文件夹中的 logs/paystack_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。密钥和客户数据绝不会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载模块会删除模块设置和日志。订单上保存的付款数据始终会保留。默认：关闭。

结账

在付款步骤中，客户选择付款方式（默认为 Paystack）并确认订单。模块会以购物车货币、购物车总额和客户的电子邮件地址发起一笔 Paystack 交易，并将客户转到 Paystack 托管的付款页面。客户在那里使用您 Paystack 账户中启用的某个渠道付款。付款页面会显示购物车编号和客户姓名。此时尚未创建订单。

付款完成后，客户返回您的商店。只有在 Paystack 确认后，订单才会被标记为已付款：客户返回时和 Webhook 到达时，模块都会通过 Paystack API 读取交易，并核对参考号、状态、金额和货币。随后订单被创建，客户会看到标准的订单确认页面。

如果付款仍在处理中，例如银行转账，客户返回时订单会以 Awaiting Paystack payment 状态创建，确认页面会显示 您的付款正在由 Paystack 确认。确认后您将收到一封电子邮件。 Webhook 会在稍后完成订单。如果客户返回时无法联系到 Paystack，Payment confirmation 页面会请客户不要重复付款，并提供 Check again 和 Back to checkout；Webhook 一到达就会创建订单。对于处于保留状态的订单，确认页面会显示 我们已收到您的付款，订单正在审核中。如有需要，我们会与您联系。

如果客户在 Paystack 页面上取消，或未付款就离开，则不会创建订单，购物车会保留。客户会带着一条消息返回结账页面，例如 付款已取消。您可以重试或选择其他付款方式。、付款未完成。您可以重试或选择其他付款方式。 或 您的付款被拒绝。您可以重试或选择其他付款方式。 每次新的尝试都会发起一笔新的 Paystack 交易。购物车较早的付款页面仍然有效：如果之后付款，仍会被接受。

订单确认页面只会在客户自己的浏览器中打开。如果在其他地方打开返回链接，付款仍会被核实，但订单不会显示：访客在结账时只会看到一条中性消息。

如果 Paystack 无法发起付款，客户会停留在结账页面，并看到一条简短消息，例如 Paystack 无法发起付款：后跟 Paystack 给出的原因，或 Paystack 暂时不可用。请稍后重试或选择其他付款方式。 购物车总额必须大于零，并且客户需要提供有效的电子邮件地址。

即使商店处于维护模式，Webhook 仍可正常工作，并且不会受到商店国家限制的影响。

在 PrestaShop 中，本模块没有内嵌或弹窗付款表单、保存的卡片、订阅、拆分付款或子账户，也不提供付款渠道选择。

订单和退款

订单状态

尚无订单：客户已被转到 Paystack，但尚未付款、已离开 Paystack 页面，或 Paystack 尚未确认付款。此时只存在购物车。

Awaiting Paystack payment：客户在 Paystack 仍在处理付款时返回，例如银行转账或 USSD。Paystack 确认付款后，订单会转为已付款状态。如果该付款始终未完成，订单将保持此状态，直到您进行更改。

Payment accepted 或 Delivered：付款已确认。开启 Autocomplete Order 时，状态为已送达。付款会以 Paystack 参考号（pscart_...）作为交易 ID 记录。备注会显示金额、参考号、交易编号、模式（测试或正式）、付款渠道、卡片类型和卡片付款的末尾数字，以及客户支付的任何 Paystack 手续费。

Paystack payment on hold：已付金额或货币与订单不一致（备注 Paystack 金额或货币不一致），例如付款开始后购物车被修改，或订单取消后才收到付款。备注会说明需要检查的内容。请处理订单或退还付款。

付款错误：Paystack 报告，处于 Awaiting Paystack payment 状态的订单的最近一次付款尝试失败或被撤销。较早尝试的失败不会改变订单。

如果某个购物车的订单已付款，之后又收到第二笔付款，订单不会改变。备注会要求您在 Paystack 后台退还重复付款。对于处于其他状态（例如 已发货）的订单收到的付款，仅会在订单上做记录。

Paystack payment 区块

订单页面会显示 Paystack payment 区块，其中包括参考号、交易 ID、模式（测试付款会带有 Test mode 标识）、付款状态、渠道和卡片、付款日期、已付和已退金额、退款记录，以及订单的 Payment notes。

退款

在 Paystack payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Paystack。确认问题 通过 Paystack 退还此金额？此操作无法撤销。。支持全额和部分退款。您需要具备编辑订单的权限；无需访问模块页面。退款会退回支付该订单的交易，并使用退款时所处模式（测试或正式）的密钥，因此该密钥必须已设置。退款以 Paystack 实际扣款的金额和货币进行，因此，对于因金额或货币不一致而处于保留状态的订单，您最多只能退还客户实际支付的金额，而不是订单总额。在 XOF 和 RWF 中，退款必须为整数金额。Paystack 会将退款排入队列：备注和退款记录会显示 Paystack 返回的状态（例如 pending）以及退款 ID。如果 Paystack 不接受退款，该区块会显示 Paystack 退款失败：及原因，并且不会记录任何退款。全额退款会将订单设为 Refunded。部分退款不会改变状态。Paystack 确认付款后，即可进行退款。

本模块不会创建退款单。订单页面上 PrestaShop 的标准退款按钮不会通过 Paystack 退款。

在 Paystack 后台进行的退款，以及 Paystack 排队处理的退款的最终状态，不会同步回 PrestaShop。如有需要，请手动记录。

许可证密钥

本模块需要从 vibefox.net 获取的 VibeFox 许可证密钥。模块的许可证区块 License — VibeFox Paystack Payment 位于 Modules > Module Manager > VibeFox Paystack Payment > Configure 页面的最上方，位于设置之上。在 License key 中输入密钥并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店移除密钥）。其下方是 Product: presta-payment-paystack 这一行，以及 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 账户中释放该名额。

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

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

故障排除

结账时不显示 Paystack：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否具有正确的密钥（测试模式使用 sk_test_... 的 Test Secret Key，正式模式使用 sk_live_... 的 Live Secret Key），以及购物车货币是否为 Paystack 支持的货币。设置顶部的状态框会指出问题。在 Payment > Preferences 中，请检查模块是否允许用于购物车货币、客户所在国家和客户群组。

付款已完成，但未创建订单：Webhook 未到达您的商店，且客户也没有返回。请在 Paystack 后台检查 Test Webhook URL 和 Live Webhook URL 是否与 Webhook URL 中显示的网址完全一致，并确认没有防火墙或密码保护阻止访问。开启 Debug log，并在 Log 字段中查看被拒绝的 Webhook。

Webhook 返回 Invalid signature：Webhook 不是使用设置中输入的测试或正式密钥签名的，例如密钥属于另一个 Paystack 账户。请输入发送 Webhook 的账户的密钥。

Webhook 返回 Secret key not configured：尚未设置任何密钥。请在设置中输入密钥。

Webhook 返回 Verification failed、Busy、retry later 或 Order could not be created, retry later：当时无法通过 Paystack API 读取交易，或购物车同时正在被客户的返回操作处理，或无法创建订单（例如模块已禁用）。Paystack 会重新发送 Webhook。日志会显示原因。

Webhook 返回 OK - unknown reference：该付款不是为本商店的购物车进行的，例如同一账户上的 Paystack 付款页面或其他集成。该请求会被忽略。

Webhook 网址在浏览器中显示 Empty body：这是正常现象。该网址只接受来自 Paystack 的请求。

客户看到「支付网关配置不正确」的消息：当前模式的密钥缺失或错误。请按照设置顶部状态框中的提示进行修正。

付款后订单处于 Paystack payment on hold：请阅读 Paystack payment 区块中的付款备注（参见订单状态），然后处理订单或退还付款。

订单仍处于 Awaiting Paystack payment：Paystack 尚未确认付款。请在 Paystack 后台检查交易和 Webhook 设置。如果客户从未完成付款，请手动更改状态。

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

开发人员可以使用模块钩子 actionWcpPaystackPaymentRequest、actionWcpPaystackSupportedCurrencies 和 actionWcpPaystackCurrencyDecimals 修改交易请求和货币列表。

卸载

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

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