VibeFox Paystack for WooCommerce — 帮助

要求

WordPress：5.8 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有它，插件无法启用。

PHP：8.0 或更高版本。

货币：订单必须使用 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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_paystack_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

5. 从 Paystack 控制台粘贴您的密钥，并在 Paystack 控制台中设置 Webhook URL（参见配置）。

6. 启用 Enable/Disable 并保存。在完成一笔测试付款之前请保持 Test Mode 开启，然后取消勾选以接受真实付款。

配置

所有设置都在同一页面中：WooCommerce > Settings > Payments > Paystack。在字段上方，状态框会显示当前模式：测试模式：不会扣除真实款项。 或 正式模式：将接受真实付款。 当当前模式的密钥为空、在密钥字段中填入了公钥（pk_...）、正式模式中使用了测试密钥（sk_test_...）或测试模式中使用了正式密钥（sk_live_...），以及 Paystack 不接受您的商店货币时，状态框也会发出警告。只要存在密钥问题，付款方式就会在结账时隐藏。在付款方式列表中，只要当前模式没有密钥，Paystack 就会标记为需要设置。

结账

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：Enable Test Mode 会对新付款使用测试密钥，不会扣除真实款项。取消勾选则使用正式密钥接受真实付款。在另一种模式下完成的付款，在验证和退款时仍会使用其自身模式的密钥。默认：开启。

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

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

Webhook

即使客户没有返回商店，Webhook 也会通知您的商店付款已完成。在 Paystack 控制台的 Settings > API Keys & Webhooks 页面中，将本节显示的 URL 同时设置为 Test Webhook URL 和 Live Webhook URL。其格式类似于 https://your-site/wc-api/paystack_p_webhook/。请完全按照设置中显示的内容复制该 URL。

Paystack 会使用您的密钥对每个 Webhook 进行签名，因此无需进行其他设置。测试 Webhook 使用测试密钥验证，正式 Webhook 使用正式密钥验证。没有有效签名的 Webhook 会被拒绝。插件使用 charge.success 事件：

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

订单

Autocomplete Order：Automatically mark orders as completed after successful payment。勾选后，已付款订单将变为“已完成”而不是“处理中”，且只进行一次状态变更并向客户发送一封邮件。默认：关闭。

高级

Debug log：Log Paystack events and API calls for debugging 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_paystack_payment。错误始终会被记录。密钥和客户数据从不写入日志。默认：关闭。

Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。停用插件不会删除任何内容。订单中保存的付款数据始终保留。默认：关闭。

结账

客户选择付款方式（默认为 Paystack）并提交订单。在测试模式下，结账页面会显示 TEST MODE ENABLED. No real charges will be made.，即已启用测试模式，不会产生真实扣款。插件会以订单货币为订单总额发起一笔 Paystack 交易，并附上订单的账单电子邮件地址，然后将客户转到 Paystack 托管的结账页面。客户在该页面使用您 Paystack 账户中启用的任一渠道付款。

付款后，客户会返回您的商店。只有在 Paystack 确认之后，订单才会被标记为已付款：客户返回时和 Webhook 到达时，插件都会使用发起付款所在模式的密钥从 Paystack API 读取交易，并核对参考号、状态、金额和货币。如果付款仍在处理中（例如银行转账），订单接收页面会显示 Your payment is being confirmed by Paystack. You will receive an email as soon as it is confirmed.（您的付款正在由 Paystack 确认，确认后您将收到一封电子邮件。）随后由 Webhook 完成订单。

如果客户在 Paystack 页面上取消，或未付款就离开页面，订单会继续等待付款。客户会带着提示信息返回结账页面或 Pay for order 页面，例如 Payment was cancelled. You can try again or choose another payment method.、The payment was not completed. You can try again or choose another payment method. 或 Your payment was declined. You can try again or choose another payment method. 客户可以再次为同一订单付款。订单之前的付款页面仍然有效：如果之后通过该页面付款，仍会被接受。

订单接收页面只对订单的客户开放：通过已签名的返回链接、创建订单的结账会话或客户账户访问。其他人会被带到结账页面并看到中性提示，而不会显示订单页面。

如果 Paystack 无法发起付款，客户会看到一条简短提示，例如 Paystack could not start the payment: 后接 Paystack 给出的原因，或 Paystack is temporarily unavailable. Please try again in a moment or choose another payment method. 订单总额必须大于零，并且订单需要有效的电子邮件地址。

该付款方式支持经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。

该插件不提供内嵌或弹窗付款表单、保存的卡片、订阅、拆分付款或子账户，也不在 WooCommerce 中提供付款渠道选择。

订单与退款

订单状态

Pending payment：客户已被转到 Paystack，但尚未付款，或在未付款的情况下离开了 Paystack 页面，或付款仍在 Paystack 处理中。当客户未付款便返回时，备注会说明订单仍在等待付款。

Processing or Completed：付款已确认。当 Autocomplete Order 开启时，状态为“已完成”。订单备注会显示金额、Paystack 参考号、交易编号、模式（测试或正式）、付款渠道，以及银行卡付款的卡类型和末四位数字，还有客户支付的任何 Paystack 手续费。订单的交易 ID 即为 Paystack 参考号（order_...）。

On hold：实际付款的金额或货币与订单不符（备注 Paystack amount or currency mismatch），或付款是在订单取消之后到达的。订单备注会说明需要检查的内容。请处理订单或退还付款。

Failed：Paystack 报告待付款订单的最近一次付款尝试已失败或被撤销。较早一次尝试的失败不会改变订单。客户可以再次付款。

如果已付款订单的第二次付款尝试也成功，订单不会改变。备注会提示您在 Paystack 控制台中退还重复付款。对于其他状态（例如 Refunded）订单收到的付款，仅会在订单上备注。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Paystack。支持全额和部分退款。只有通过经验证的 Paystack 交易付款的订单才会显示退款按钮。退款会针对支付该订单的交易进行，并使用退款发起时所在模式（测试或正式）的密钥，因此必须已设置该模式的密钥。在 XOF 和 RWF 中，退款必须为整数金额。Paystack 会将退款排入队列：订单备注会显示 Paystack 返回的状态（例如 pending）以及退款 ID。如果 Paystack 不接受退款，WooCommerce 会显示 Paystack refund failed: 及原因，并且不会记录退款。

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

许可证密钥

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

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

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

许可证到期后，插件仍可正常运行，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

结账时没有显示 Paystack：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式是否有正确的密钥（测试模式使用 sk_test_... 的 Test Secret Key，正式模式使用 sk_live_... 的 Live Secret Key），以及订单货币是否为 Paystack 支持的货币。设置顶部的状态框会说明问题所在。

付款已完成，但订单仍为 Pending payment：Webhook 没有到达您的商店，并且客户也没有返回。请在 Paystack 控制台中检查 Test Webhook URL 和 Live Webhook URL 是否与设置中显示的 URL 完全一致，并确认没有维护模式、防火墙或密码保护阻止它。请在 WooCommerce > Status > Logs 中查看来源为 wcp_paystack_payment 的日志，查找被拒绝的 Webhook。

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

Webhook 返回 Secret key not configured：两个密钥都未设置。请在设置中输入密钥。

Webhook 返回 Verification failed 或 Busy, retry later：当时无法通过 Paystack API 读取交易，或者订单正被客户返回的动作同时更新。订单不会被改动，Paystack 会再次发送 Webhook。

Webhook 返回 OK - unknown reference：该付款并非针对本商店的订单，例如 Paystack 付款页面或同一账户中的其他集成。它会被忽略。

客户看到 Payment gateway is not properly configured：当前模式的密钥缺失或错误。请按照设置顶部状态框的提示进行修正。

付款后订单处于 On hold：请阅读订单备注。付款的金额或货币与订单不符，或付款是在订单取消之后到达的。请处理订单或退还付款。

退款因模式相关消息失败：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入密钥后重试。消息 No verified Paystack payment was found for this order 表示该订单并非通过经验证的 Paystack 交易付款。请在 Paystack 控制台中退款。

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

卸载

停用插件会保留所有数据。要删除插件，请先在 Plugins 页面中停用，然后删除。本插件的许可证密钥和许可证状态始终会被删除。只有在开启了 Delete data on uninstall 时，网关设置和日志才会被删除；否则会保留，以便日后重新安装。现有订单会保留其付款备注、交易 ID 和 Paystack 参考号。

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