VibeFox PayFast for WooCommerce — 帮助
系统要求
WordPress：6.2 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。
PHP：8.0 或更高版本。
货币：南非兰特（ZAR），在 WooCommerce > Settings > General 中设置。PayFast 仅以兰特结算。最低订单金额为 R5.00。
PayFast 账户：您的 PayFast 账户的 Merchant ID 和 Merchant Key，可在 PayFast 后台的 Settings > Developer Settings 中找到。强烈建议设置密码短语（passphrase）；如果已在 PayFast 中设置，则必须在插件中输入相同的密码短语。测试时需要 PayFast 沙盒的凭据。
可访问的站点：付款通知 URL 必须可从互联网访问，不能处于维护模式，也不能有基本身份验证或防火墙拦截。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_payfast_pay 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 在 WooCommerce > Settings > General 中将店铺货币设置为南非兰特。
4. 打开设置：WooCommerce > Settings > Payments > PayFast > Manage，或在插件页面中点击插件名称下方的 Settings。
5. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
6. 输入 Merchant ID、Merchant Key 和密码短语。测试时，请保持 Test mode 开启，并输入您的沙盒凭据。
7. 启用 Enable/Disable 并保存。进行一次测试付款，然后关闭测试模式以接收真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > PayFast。在字段上方，页面会在以下情况发出警告：当前模式的凭据为空（此时结账页面会隐藏 PayFast）、店铺货币不是 ZAR、实时模式使用了公共沙盒 Merchant ID 10000100，或未设置密码短语；测试模式开启时，还会显示 Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. 在支付方式列表中，PayFast 会被标记为需要设置，直到输入当前模式的 Merchant ID 和 Merchant Key 为止。
常规
Enable/Disable：Enable PayFast 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：PayFast。
Description：结账时显示在付款方式下方的文字。默认：Pay securely by card, Instant EFT and other methods on the PayFast payment page.
PayFast 账户（实时）
您可以在 PayFast 后台的 Settings > Developer Settings 中找到 Merchant ID 和 Merchant Key。如果您在那里设置了密码短语，请在此处输入完全相同的内容。
Merchant ID：您的 PayFast 实时 Merchant ID。
Merchant Key：您的 PayFast 实时 Merchant Key。每个付款表单都会将其发送给 PayFast。
Passphrase：PayFast 中的盐值密码短语，位于 Settings > Developer Settings。强烈建议设置：它用于签名付款和通知。
沙盒（测试模式）
在测试模式下，付款会发送到 PayFast 沙盒，不会扣除任何真实资金。登录 PayFast 沙盒后会显示沙盒凭据（公共测试商户为 10000100 / 46f0cd694581a）。
Test mode：Use the PayFast sandbox and the sandbox credentials below。在结账页面，顾客会看到 TEST MODE: payments go to the PayFast sandbox, no real money is charged. 默认：开启。
Sandbox Merchant ID：您沙盒账户的 Merchant ID。
Sandbox Merchant Key：您沙盒账户的 Merchant Key。
Sandbox Passphrase：仅当您的沙盒账户中设置了密码短语时填写。
如果您在测试模式下从 1.0 版本升级，现有凭据会被复制到沙盒字段中。关闭测试模式之前，请先检查实时凭据。
付款通知（ITN）
PayFast 会通过服务器对服务器的通知，将每笔付款确认发送到本节显示的 URL。其格式如下：https://your-site/wc-api/payfast_pay/。该地址会随每笔付款一起发送，因此无需在 PayFast 中进行配置，但该地址必须可从互联网访问。
来源检查：Accept live notifications only from PayFast servers。这些地址来自 PayFast 的 DNS 记录。仅当您的站点位于会隐藏访客地址的代理或 CDN 之后时，才应关闭此项。签名和服务器确认始终会进行检查。沙盒通知不按地址检查。默认：开启。
高级
Debug log：Log payment steps 会将各步骤写入 WooCommerce > Status > Logs，来源为 wcp_payfast_pay。错误始终会被记录。不会写入密码短语或顾客信息。默认：关闭。
Uninstall：Delete the gateway settings and logs when the plugin is deleted。默认：关闭。
结账
顾客选择付款方式（默认为 PayFast）并下单。顾客会进入订单的 Pay for order 页面，该页面显示 Thank you for your order. You are being redirected to PayFast to complete the payment.，并自动将已签名的付款表单发送至 PayFast。如果浏览器没有自动继续，顾客可点击 Pay with PayFast；点击 Cancel order 则会取消订单。该表单包含以 ZAR 计价的订单总额、Order # 及订单号、顾客的姓名和电子邮件以及订单密钥。每次打开页面时都会重新生成，因此顾客从 PayFast 返回后可以再次打开。
在 PayFast 页面上，顾客可使用银行卡、Instant EFT 或您 PayFast 账户中的其他方式付款。随后，PayFast 会将付款通知（ITN）发送到您的店铺。只有当通知通过以下所有检查时，订单才会被标记为已付款：
顾客返回订单已接收页面并不会改变订单状态。在通知到达之前，页面会显示 PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 如果订单处于保留状态，则会显示 Your payment is being reviewed. We will contact you if anything else is needed.
如果顾客在 PayFast 页面上取消，订单将按照 WooCommerce 的标准方式取消。如果顾客未付款就离开，订单将保持未付款状态，可以通过 Pay for order 页面再次付款。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。当当前模式的凭据缺失、店铺或订单货币不是 ZAR，或总额低于 R5.00 时，该付款方式会被隐藏。它兼容 WooCommerce 高性能订单存储（HPOS）。
该插件仅接受以 ZAR 计价的一次性付款。它不支持通过 WooCommerce 退款、订阅、已保存（令牌化）的银行卡、预购或分单付款。
订单
订单状态
Pending payment：顾客已被引导至 PayFast，但付款通知尚未到达。
Processing：PayFast 已确认付款。这是付款后 WooCommerce 的标准状态；仅包含虚拟可下载商品的订单会变为已完成。订单备注会显示 PayFast 付款 ID，该 ID 同时也是订单的交易 ID。沙盒付款会收到一条备注，说明未扣除真实资金。PayFast 手续费和净额会保存在订单中。
On hold：PayFast 将付款报告为待处理；或已付金额与订单总额不符，或订单不是 ZAR；或订单已被取消后又收到了付款。订单备注会说明原因。请检查订单和您的 PayFast 后台，然后发货或在 PayFast 中退款。
Failed：订单未付款时，PayFast 将付款报告为失败。顾客可以重新付款。
Cancelled：顾客在 PayFast 页面上取消，或订单被您取消，或被 WooCommerce 库存保留超时取消。
同一笔付款的重复通知不会产生任何变化。如果对已付款的订单又收到另一笔已完成的付款，备注会提醒您在 PayFast 中退还重复的付款。对已退款订单收到的付款只会添加备注。当网关处于实时模式时收到的沙盒付款会添加备注，但不会将订单标记为已付款。
退款
WooCommerce 不支持退款。请在您的 PayFast 后台退还付款，然后在 WooCommerce 中创建手动退款。
许可证密钥
该插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > PayFast 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 PayFast。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认。
许可证过期后，插件仍会继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 PayFast：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的 Merchant ID 和 Merchant Key 是否已填写、店铺货币是否为 ZAR，以及订单总额是否至少为 R5.00。缺少任何项目时，设置页面都会显示警告。
付款已完成，但订单仍处于待付款状态：PayFast 无法送达付款通知，或通知被拒绝。请开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_payfast_pay。常见原因包括：站点无法从互联网访问（维护模式、基本身份验证、防火墙）；PayFast 与插件中的密码短语不一致；或者在实时模式下位于代理或 CDN 之后时的来源检查。此时请关闭 Source check。
通知返回 Invalid signature：插件中的密码短语与 PayFast 为该模式设置的不一致。
通知返回 Invalid source：通知并非来自 PayFast 地址，或代理或 CDN 隐藏了真实地址。如果您的站点位于代理或 CDN 之后，请关闭 Source check。
通知返回 Merchant mismatch 或 Order mismatch：付款是支付给另一个 PayFast 账户的，或不属于此订单。不会做任何更改。
通知返回 Confirmation unavailable 或 Busy：无法连接 PayFast 进行服务器确认，或同一订单的另一通知正在同时处理。PayFast 会重试该通知。
通知返回 Not configured：订单付款所用模式的凭据缺失。
顾客看到 PayFast accepts payments from R5.00：订单总额低于 PayFast 的最低限额。
订单处于 On hold：PayFast 确认的付款与订单不符（金额不同，或货币不是 ZAR），或订单已取消后又收到了付款。请检查订单备注和您的 PayFast 后台。
沙盒付款未能支付订单：网关处于实时模式。在实时模式下，沙盒付款绝不会支付订单；订单上的备注会说明这一点。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会沿用最后已知的状态继续运行。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、插件的其他选项、缓存的 PayFast 地址及其日志，只有在 Delete the gateway settings and logs when the plugin is deleted 已开启时才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。
PayFast 是其所有者的商标。本插件与 PayFast 无关联，也未获得其认可。