VibeFox PayFast for OpenCart — 帮助

要求

OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP: 8.0 或更高版本。

Currency: 南非兰特（ZAR）。PayFast 仅以兰特结算，因此订单必须使用 ZAR。如果您的商店尚未添加该货币，请在 System > Localisation > Currencies 中添加。订单最低金额为 R5.00。

PayFast account: 您的 PayFast 账户的 Merchant ID 和 Merchant Key，可在 PayFast 后台的 Settings > Developer Settings 中找到。强烈建议设置口令短语（passphrase）；如果您在 PayFast 中设置了口令短语，则必须在扩展中输入完全相同的口令短语。测试时需要 PayFast 沙盒的凭据。

Reachable store: 付款通知 URL 必须能够从互联网访问，不能有基本身份验证或防火墙拦截。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请将其解压到您的电脑上。压缩包中包含 README.txt、OpenCart 3 安装包 wcp_payfast_pay-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_payfast_pay.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payfast_pay-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayFast Pay Gateway，点击 Install（绿色的 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key，然后点击 Activate（参见“许可证密钥”部分）。

4. 输入 Merchant ID、Merchant Key 和口令短语。测试时请保持 Test mode 开启，并输入您的沙盒凭据。

5. 开启 Enable/Disable 并点击 Save。进行一次测试付款，然后关闭 Test mode，即可接收真实付款。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payfast_pay.ocmod.zip。请不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayFast Pay Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 输入许可证密钥和 PayFast 凭据，并按照 OpenCart 3 的步骤 3 至 5 测试付款。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见 Notification URL）；它同样会随每笔付款一起发送给 PayFast。

新安装默认关闭付款方式，并开启测试模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果当前模式的凭据为空（此时 PayFast 会在结账时隐藏）、商店默认货币不是 ZAR、正式模式使用了公共沙盒 Merchant ID 10000100，或未设置口令短语，页面都会发出提醒。测试模式开启时，页面会显示 Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，所选的地理区域和订单状态必须存在；否则不会保存任何内容，并且页面会指出对应字段。如果在缺少当前模式凭据的情况下启用付款方式，设置会保存，但会显示警告。

PayFast

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

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

Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Sort Order: PayFast 在结账时付款方式中的排列位置。留空或输入整数。

Geo Zone: 仅对所选地理区域内的付款地址提供 PayFast。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，若商店不要求付款地址，则使用配送地址。

Total: 订单必须达到的结账金额（以商店默认货币计）才会提供 PayFast。留空则对任何金额都提供 PayFast。PayFast 本身始终要求至少 R5.00。

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 中的 salt 口令短语。强烈建议设置：它用于对付款和通知进行签名。

沙盒（测试模式）

在测试模式下，付款会发送到 PayFast 沙盒，不会扣除任何真实款项。登录 PayFast 沙盒后会显示沙盒凭据（公共测试商户为 10000100 / 46f0cd694581a）。

Test mode: Use the PayFast sandbox and the sandbox credentials below。开启时，顾客在 Confirm Order 步骤会看到 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: 仅当您的沙盒账户中设置了口令短语时才需要填写。

已保存的口令短语不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的口令短语，请勾选字段下方的 Clear the saved passphrase on save，然后点击 Save。

付款通知（ITN）

Notification URL: PayFast 会通过服务器到服务器的通知，将每笔付款的确认发送到此处显示的 URL。它在 OpenCart 3 中的格式类似 https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn，由您 OpenCart 安装的商店地址生成。该地址会随每笔付款一起发送，因此无需在 PayFast 中进行配置，但它必须能够从互联网访问。订单只会根据这些经过验证的通知获得状态；顾客返回商店并不会改变订单。

Source check: 正式环境的通知只接受来自 PayFast 服务器的请求。这些地址来自 PayFast 的 DNS 记录（缓存 6 小时；保存设置时缓存会重置）以及 PayFast 公布的地址范围。只有当您的商店位于会隐藏访客地址的代理或 CDN 之后时，才应将其关闭。签名和服务器确认始终会进行检查。沙盒通知不按地址检查。默认：开启。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有经过验证的 PayFast 通知才会为其设置状态。被取消、失败或中途放弃的付款会使订单保持无状态，顾客可以重新付款。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status (paid): PayFast 确认付款且金额和货币相符后的状态。默认：处理中。

Awaiting PayFast payment: PayFast 将付款报告为待处理（例如 Instant EFT）。当 PayFast 完成付款后，状态会变为已付款。默认：待处理。

PayFast payment on hold: 需要您审核的付款（参见“订单状态”部分）。此类订单不会被标记为已付款；备注会说明原因。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Payment failed: 待处理的付款失败。如果 PayFast 之后完成该付款，订单会变为已付款状态。默认：失败。

高级

Debug log: 将付款步骤记录到 OpenCart 日志文件夹（storage/logs）中的 payfast_p_debug.log.php。该文件无法通过网页打开；当大小达到 5 MB 时，会被移动到 payfast_p_debug.old.log.php。即使开关关闭，错误和警告仍会始终记录。不会写入口令短语、密钥或顾客信息。默认：关闭。

Log: 显示日志的大小和最新记录。点击 Clear log 可清空日志。

Uninstall: Delete the gateway settings when the extension is uninstalled（设置、缓存的 PayFast 地址和日志）。PayFast 付款记录和订单始终会保留。默认：关闭。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。口令短语不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的口令短语会被保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 PayFast）。在 Confirm Order 步骤，顾客会看到您的描述以及说明 Thank you for your order. You will be redirected to PayFast to complete the payment. OpenCart 在此步骤创建订单，此时仍无状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会将已签名的付款表单发送给 PayFast。该表单包含以 ZAR 计的订单金额、Order #（订单号）、顾客的姓名和电子邮件、付款参考（订单号和尝试次数）以及本次尝试的随机令牌。每次新的尝试都会获得新的参考和令牌。

在 PayFast 页面，顾客可以使用银行卡、Instant EFT 或您 PayFast 账户中的其他方式付款。随后，PayFast 会将付款通知（ITN）发送到您的商店。只有当 PayFast 发送的通知通过了所有检查并确认付款后，订单才会被标记为已付款：

之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。同一购物车的通知会逐个处理；如果同一购物车的另一条通知正在处理中，PayFast 会收到错误响应并重新发送通知。即使商店处于维护模式，通知 URL 仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动操作（startup action），使通知以及顾客从 PayFast 返回的请求得以放行。

顾客返回时，如果订单已有状态，就会显示 OpenCart 的订单成功页面。如果 PayFast 将付款报告为待处理，页面还会显示 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. 如果待处理的付款随后失败，则显示 Your PayFast payment was not completed. Please contact us about this order.（在 OpenCart 4 中，顾客会被送回结账页面，见下文）。 如果通知尚未到达，则会显示 Payment confirmation 页面，说明 PayFast 正在确认付款，并提供 Check again 和 Back to checkout 按钮。

如果顾客在 PayFast 页面上取消，会返回结账页面，并显示 The PayFast payment was cancelled. You can try again or choose another payment method. 如果 PayFast 将付款报告为失败，提示信息为 The payment was not completed. You can try again or choose another payment method. 购物车会被保留，并可以再次付款。在 OpenCart 4 中，这些提示显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则为结账保留一个订单并对其进行更新，因此在付款被取消或失败后，顾客会以新的尝试为同一订单付款。如果同一购物车中的另一笔订单已经由 PayFast 处理（例如在第二个浏览器标签页中），顾客会被引导至成功页面，而不是再次付款。

在显示成功页面之前，OpenCart 4 会将订单保留在结账流程中。如果该订单在此期间未付款即已关闭（例如其待处理的付款失败，或您取消了它），顾客会被送回结账页面，并显示 Your previous order was cancelled or its payment failed. Please confirm the order again.，下一次点击 Confirm Order 将为一个新订单付款。如果该订单已有状态，而购物车中现在包含其他商品或数量，则显示的消息为 Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.

当当前模式的凭据缺失、结账货币不是 ZAR 或总额低于 R5.00 时，付款方式会被隐藏。如果顾客仍然进入了付款环节，按钮上方会出现简短提示进行说明，例如 PayFast accepts payments from R5.00. Please choose another payment method.

该扩展仅接受以 ZAR 计的一次性付款。它不支持从订单页面退款、不支持订阅、不支持保存（令牌化）的银行卡，也不支持拆分付款。

订单

订单状态

No status (missing order): 顾客已被转到 PayFast，但付款通知尚未到达，或者 PayFast 将付款报告为失败。在 Sales > Orders 中，此类订单仅在筛选器 Order Status 设置为 Missing Orders 时显示。

在 OpenCart 4 中，结账过程中未付款的订单在顾客返回 Confirm Order 步骤时，可能会被设为 Voided 状态。扩展会将此类订单视为无状态订单，之后的付款仍会确认该订单。

Order Status (paid) (default Processing): PayFast 已确认付款。备注中会显示 PayFast 付款 ID。沙盒付款会附带一条备注，说明未扣除任何真实款项。

Awaiting PayFast payment (default Pending): PayFast 将付款报告为待处理。当 PayFast 完成付款时，订单会变为已付款状态；如果付款失败，则变为 Payment failed。顾客会通过电子邮件收到这些变化的通知。

Payment failed (default Failed): 待处理的付款失败。如果 PayFast 之后完成该付款，订单会变为已付款状态。

PayFast payment on hold (default Pending): 实付金额与订单总额不符，或订单不使用 ZAR；收到的付款对应的订单，其状态已被您在此期间更改（例如已取消），或其付款方式已不再是 PayFast；或者在网关处于正式模式时收到了沙盒付款。备注会说明情况。请检查订单和您的 PayFast 后台，然后将订单设为已付款状态，或取消订单并在 PayFast 中退款。

同一笔付款的重复通知不会产生任何变化。迟到的失败或待处理通知永远不会改变已付款的订单。如果对已付款订单，或对已付款购物车的第二个订单，又收到一笔已完成的付款，已付款订单上的备注会提示您在 PayFast 中退还重复的款项。

备注是订单 History 中的记录，顾客看不到。

VibeFox PayFast Pay Gateway 选项卡

在 Sales > Orders 中打开一笔通过 PayFast 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的 VibeFox PayFast Pay Gateway 选项卡会显示 Payment reference (m_payment_id)、PayFast payment ID、Environment（正式或沙盒）、请求金额、状态、以 ZAR 计的毛额、手续费和净额，以及 PayFast notes。对于处于保留状态的订单，它会显示一条提醒，建议您检查付款。该选项卡仅对有权访问扩展的用户显示。

退款

不支持从订单页面退款。请在您的 PayFast 后台退还付款，然后在 OpenCart 中手动更新订单。

许可证密钥

该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayFast Pay Gateway 位于 Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit 页面，是设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），还提供以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除该密钥）。其下方是 Product: opencart-payment-payfast 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文本跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改商店地址后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续沿用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 PayFast。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍然可以在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览功能不可用：商店看不到后台登录状态，因此在没有有效密钥的情况下，付款方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 将其关闭，可隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认。

许可证到期后，扩展会继续运行，但更新和支持需要续期。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会移除许可证密钥和许可证状态。

故障排除

PayFast does not appear at checkout: 请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Merchant ID 和 Merchant Key 是否已填写、结账货币是否为 ZAR，以及订单总额是否至少为 R5.00。缺少任何项目时，设置页面都会显示警告。另请检查付款地址是否在所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

The payment went through, but the order stays without a status: PayFast 无法送达付款通知，或通知被拒绝。请查看扩展页面上的 Log 字段；错误和被拒绝的通知始终会被记录，Debug log 则会记录每一步。常见原因：商店无法从互联网访问（基本身份验证、防火墙）、PayFast 与扩展中的口令短语不一致，或者在正式模式下位于代理或 CDN 之后时出现的来源检查问题。这种情况下请关闭 Source check。

The notification answers Invalid signature: 扩展中的口令短语与付款所用模式在 PayFast 中设置的口令短语不一致。

The notification answers Invalid source: 通知并非来自 PayFast 地址，或者代理或 CDN 隐藏了真实地址。如果您的商店位于代理或 CDN 之后，请关闭 Source check。

The notification answers Merchant mismatch or Order mismatch: 付款被支付到了另一个 PayFast 账户，或不属于本次付款尝试。不会做任何更改。

The notification answers Order not found: 该付款参考对本商店而言未知。不会做任何更改。

The notification answers Confirmation unavailable, Busy or Temporary error: 无法连接 PayFast 进行服务器确认，或同一购物车的另一条通知恰好正在处理，或无法设置订单状态。PayFast 会重试该通知。日志会显示原因。

The notification answers Not configured: 付款发起时所用模式的凭据缺失。请重新输入，例如测试付款所用的沙盒凭据。

The customer sees PayFast accepts payments in South African rand (ZAR) only: 订单使用的是其他货币。请让顾客使用兰特付款，或让其选择其他付款方式。

The customer sees This payment method is not available. Please reload the checkout page. 结账会话已与订单不再匹配，或付款方式在此期间被关闭。顾客需要重新加载结账页面。

Order is in the on-hold status: 请阅读 VibeFox PayFast Pay Gateway 选项卡中的备注（参见“订单状态”部分）和您的 PayFast 后台，然后设置为已付款状态或退还付款。

A sandbox payment did not pay the order: 网关处于正式模式。在正式模式下，沙盒付款永远无法支付订单；订单中的备注会说明这一点。

对开发者：在付款表单签名之前，扩展会连同表单字段和订单一起触发 OpenCart 事件 payfast_p_payment_data。商户凭据、URL、付款参考、金额和令牌均无法通过该事件修改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayFast Pay Gateway 旁边的 Uninstall（红色 −）按钮。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态；这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，同时移除其事件，以及让维护模式下的通知和顾客从 PayFast 返回的启动操作，即 startup action）。如果开启了 Delete the gateway settings when the extension is uninstalled，则其余网关设置（标题、描述、凭据、口令短语、测试模式、来源检查、日志记录）、缓存的 PayFast 地址和日志都会被删除；如果关闭，则会保留，以便日后重新安装时使用。PayFast 付款记录和订单始终会保留。已有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PayFast Pay Gateway 旁边的 Uninstall（橙色 −）按钮，然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

PayFast 是其各自所有者的商标。本扩展与 PayFast 无关联，也未获得 PayFast 的认可。