VibeFox PayFast for PrestaShop — 帮助
要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。版本低于此要求时，模块拒绝安装。
货币：南非兰特（ZAR）。PayFast 仅以兰特结算，因此购物车必须使用 ZAR。如果您的店铺尚未添加该货币，请在 International > Localization > Currencies 中添加。最低订单金额为 R5.00。
PayFast 账户：您的 PayFast 账户的 Merchant ID 和 Merchant Key，可在 PayFast 控制台的 Settings > Developer Settings 中找到。强烈建议设置密码短语（passphrase）；如果您在 PayFast 中设置了密码短语，则必须在模块中输入相同的密码短语。测试时需要 PayFast 沙盒的凭据。
可访问的店铺：付款通知 URL 必须可以从互联网访问，不能有基本认证（basic auth）或防火墙拦截。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox PayFast Pay Gateway，然后点击 Configure。
3. 在 Configure 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入 Merchant ID、Merchant Key 和密码短语（passphrase）。测试时，保持 Test mode 开启，并输入您的沙盒凭据。
5. 开启 Enable/Disable，然后点击 Save。进行一次测试付款，然后关闭 Test mode 以接收真实付款。
安装时，模块会创建两个订单状态：Awaiting PayFast payment 和 PayFast payment on hold。PrestaShop 会为所有货币、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中进行限制；请确保该模块仍允许用于兰特。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。在字段上方，页面会在以下情况发出警告：当前模式的凭据为空（此时 PayFast 在结账时隐藏）；默认店铺货币不是 ZAR；实时模式使用公共沙盒 Merchant ID 10000100；未设置密码短语。当测试模式开启且模块已启用时，会显示：测试模式已开启：订单将在 PayFast 沙盒中支付，不会扣除真实款项。 留空的 Title 会被拒绝，并提示：请输入付款方式的标题。
PayFast
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 的 salt 密码短语，位于 Settings > Developer Settings。强烈建议设置：它用于对付款和通知进行签名。
沙盒（测试模式）
在测试模式下，付款会发送至 PayFast 沙盒，不会扣除真实款项。登录 PayFast 沙盒后会显示沙盒凭据（公共测试商户为 10000100 / 46f0cd694581a）。
Test mode：Use the PayFast sandbox and the sandbox credentials below。开启时，客户会在付款方式下方看到：测试模式：付款将发送至 PayFast 沙盒，不会扣除真实款项。 默认：开启。
Sandbox Merchant ID：您沙盒账户的 Merchant ID。
Sandbox Merchant Key：您沙盒账户的 Merchant Key。
Sandbox Passphrase：仅当您的沙盒账户中设置了密码短语时填写。
已保存的密码短语不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved passphrases：勾选 Passphrase 或 Sandbox Passphrase，然后点击 Save 以删除。空字段会保留已保存的值。
付款通知（ITN）
Notification URL：PayFast 会通过服务器对服务器的通知，向此处显示的 URL 确认每笔付款。启用友好 URL 时，它类似于 https://your-shop/module/wcp_payfast_pay/itn，可能还带有默认语言的语言代码。该地址会随每笔付款发送，因此无需在 PayFast 中进行任何配置，但它必须可以从互联网访问。只有经过验证的通知才会创建订单；客户返回店铺不会创建或支付订单。
Source check：仅接受来自 PayFast 服务器的实时通知。这些地址来自 PayFast 的 DNS 记录（缓存 6 小时）以及 PayFast 公布的地址范围。只有当您的店铺位于隐藏访问者地址的代理或 CDN 之后时才需关闭。签名和服务器确认始终会进行检查。沙盒通知不按地址检查。默认：开启。
高级
Debug log：将付款步骤记录到模块文件夹中的 logs/payfast_p_debug.log.php。该文件无法通过 Web 访问。即使开关关闭，错误和警告也始终会被记录。不会写入密码短语或客户信息。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Uninstall：Delete the gateway settings when the module is uninstalled（设置、缓存的 PayFast 地址和日志）。PayFast 付款记录、订单和订单状态始终会被保留。默认：关闭。
结账
在付款步骤中，客户选择付款方式（默认为 PayFast）并确认。显示 感谢您的订单。正在将您重定向至 PayFast 完成付款。 的页面会自动将已签名的付款表单发送至 PayFast。如果浏览器未自动继续，客户可点击 Pay with PayFast；点击 Cancel 则返回结账页面。表单包含以 ZAR 计价的购物车总额、Cart #（购物车编号）、客户的姓名和电子邮件、付款参考号（购物车编号和尝试次数）以及本次尝试的随机令牌（token）。此时尚不存在订单。每次新的尝试都会获得新的参考号和令牌。
在 PayFast 页面，客户可使用银行卡、Instant EFT 或您 PayFast 账户中的其他方式付款。随后 PayFast 会向您的店铺发送付款通知（ITN）。只有 PayFast 以通过所有检查的通知确认付款后，订单才会被标记为已付款：
同一购物车的通知会逐一处理。如果同一购物车的另一条通知正在处理中，PayFast 会收到错误应答并重新发送通知。店铺处于维护模式时，通知 URL 仍然有效，且不受店铺的国家限制影响。
客户返回且订单已存在时，会显示标准的订单确认页面。如果 PayFast 报告付款为待处理，页面会显示：PayFast 正在确认您的付款。确认后您将收到电子邮件——无需再次付款。 如果订单处于待审核状态，页面会显示：您的付款正在审核中。如需其他信息，我们会与您联系。 如果待处理的付款之后失败，页面会显示：您的 PayFast 付款未完成。请就此订单与我们联系。 如果通知尚未到达，将显示 Payment confirmation 页面，说明 PayFast 正在确认付款，并且订单将在 PayFast 确认后创建，同时提供 Check again 和 Back to checkout 按钮。
如果客户在 PayFast 页面取消，将返回结账页面，并显示：PayFast 付款已取消。您可以重试，或选择其他付款方式。 如果 PayFast 报告付款失败，则显示：付款未完成。您可以重试，或选择其他付款方式。 购物车会被保留，可以再次付款。
当当前模式的凭据缺失、购物车货币不是 ZAR 或不被模块允许，或总额低于 R5.00 时，付款方式会被隐藏。如果客户仍然进入了付款环节，会显示一条简短说明，例如：PayFast 接受 R5.00 及以上的付款。请选择其他付款方式。
本模块仅接受以 ZAR 计价的一次性付款。不支持在订单页面退款、不支持订阅、不支持已保存（令牌化）的银行卡以及分单付款。
订单
订单状态
No order yet：客户已被转至 PayFast，但付款通知尚未到达；或 PayFast 报告付款失败。此时仅存在购物车。
Payment accepted：PayFast 已确认付款。付款以 PayFast 付款 ID 作为交易 ID 记录，并且备注中显示付款 ID。沙盒付款会附带备注，说明并未扣除真实款项。
Awaiting PayFast payment：PayFast 报告付款为待处理。当 PayFast 完成付款后，订单会转为 Payment accepted。
Payment error：待处理的付款失败。如果 PayFast 之后完成该付款，订单将变为 Payment accepted。
PayFast payment on hold：已付金额与购物车总额不一致，或购物车不是 ZAR；收到的付款针对的是已取消的订单，或其付款方式已不再是 PayFast；或者在网关处于实时模式时收到了沙盒付款。PayFast 收到的金额会记录在订单上（沙盒付款除外），备注会说明原因。请检查订单和您的 PayFast 控制台，然后将订单设为 Payment accepted，或取消订单并在 PayFast 中退款。
同一笔付款的重复通知不会产生任何变化。延迟到达的失败或待处理通知绝不会改变已付款的订单。如果已付款的订单又收到另一笔已完成的付款，备注会提醒您在 PayFast 中退还重复付款。针对已退款订单的付款只会添加一条备注。
PayFast 付款模块
订单页面会显示一个 PayFast payment 模块，包含付款参考号（m_payment_id）、PayFast 付款 ID、环境（实时或沙盒）、状态、以 ZAR 计价的总额、手续费和净额，以及本模块的备注。对于处于待审核状态的订单，它会显示提醒您检查付款的信息。
退款
不支持在订单页面退款。请在 PayFast 控制台中退还付款，然后在 PrestaShop 中手动更新订单。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。模块 Configure 页面顶部、设置上方的许可证区块 License — VibeFox PayFast Pay Gateway 是 Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure 中的第一个区块。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥，以及状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-payfast 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。店铺地址变更后，或在账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥仅适用于一个域名：主店铺的域名，多店铺配置下同样如此。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向客户显示 PayFast。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。在您使用后台期间，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 PayFast：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Merchant ID 和 Merchant Key 是否已填写、购物车是否为 ZAR，以及订单总额是否至少为 R5.00。缺少任何项目时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于兰特、客户所在国家以及客户所属群组。
付款已成功，但未创建订单：PayFast 无法送达付款通知，或通知被拒绝。请查看模块页面上的 Log 字段；错误和被拒绝的通知始终会被记录，Debug log 还会记录每个步骤。常见原因：店铺无法从互联网访问（basic auth、防火墙）；PayFast 与模块中的密码短语不一致；或者在实时模式下店铺位于代理或 CDN 之后，导致来源检查失败。此时请关闭 Source check。
通知返回 Invalid signature：模块中的密码短语与付款所用模式在 PayFast 中设置的密码短语不一致。
通知返回 Invalid source：通知并非来自 PayFast 地址，或代理或 CDN 隐藏了真实地址。如果店铺位于代理或 CDN 之后，请关闭 Source check。
通知返回 Merchant mismatch 或 Order mismatch：付款是发给另一个 PayFast 账户的，或不属于此付款尝试。不会做任何更改。
通知返回 Order not found：该店铺无法识别此付款参考号。不会做任何更改。
通知返回 Confirmation unavailable、Busy 或 Temporary error：无法联系 PayFast 进行服务器确认；同一购物车的另一条通知恰好正在处理中；或订单无法创建（例如模块已禁用）。PayFast 会重试该通知。日志会显示具体原因。
通知返回 Not configured：付款发起时所处模式的凭据缺失。请重新输入，例如测试付款所需的沙盒凭据。
客户看到“PayFast 仅接受南非兰特（ZAR）付款”：购物车使用的是其他货币。请让客户使用兰特付款，或选择其他付款方式。
订单为 PayFast payment on hold：请阅读 PayFast payment 模块中的备注（参见订单状态）以及您的 PayFast 控制台，然后接受订单或退款。
沙盒付款未能支付订单：网关处于实时模式。沙盒付款在实时模式下绝不会支付订单；订单上的备注会说明这一点。
面向开发者：钩子 actionPayfastPPaymentData 可以在付款表单字段签名之前修改这些字段。它无法修改商户凭据、URL、付款参考号、金额和令牌。
卸载
进入 Modules > Module Manager，打开 VibeFox PayFast Pay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果开启了 Delete the gateway settings when the module is uninstalled，则会删除网关设置、缓存的 PayFast 地址和日志。如果关闭，则所有设置都会保留，以便日后重新安装。PayFast 付款记录、订单以及订单状态 Awaiting PayFast payment 和 PayFast payment on hold 始终会被保留。现有订单会保留其付款备注和交易 ID。
PayFast 是其各自所有者的商标。本模块与 PayFast 无关联，也未获得 PayFast 的认可或背书。