VibeFox Pesapal for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：订单必须使用 KES、UGX、TZS、ZMW、RWF 或 USD。使用其他货币时，结账页面会隐藏该付款方式。订单以其自身货币扣款；扩展不进行货币换算。金额以主货币单位发送，并按货币的精度取整（UGX 和 RWF 无小数位）。

Pesapal 账户：您需要一个 Pesapal 商户账户的 consumer key 和 consumer secret。沙盒密钥和正式密钥是不同的。沙盒密钥来自 cybqa.pesapal.com 上的演示商户账户（Pesapal 也在其开发者门户发布演示密钥）。正式密钥来自您的 Pesapal 商户后台。Pesapal 后台无需进行其他设置：扩展会自行注册其通知 URL。由于 Pesapal 会向您的店铺发送付款通知，因此您的店铺必须可以从互联网访问。

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

安装

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

OpenCart 3

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

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Pesapal Pay Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要拥有修改付款扩展列表的权限。

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

4. 输入沙盒的 consumer key 和 consumer secret，开启 Enable/Disable，点击 Save，然后进行一次测试下单。

5. 输入正式环境的 consumer key 和 consumer secret，关闭 Sandbox mode，然后点击 Save，即可接受真实付款。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pesapal_pay.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法工作。

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

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

4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥和 Pesapal 密钥。两个版本的设置页面及其字段相同。只有 IPN URL 不同（参见付款通知）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。设置上方的标签会显示当前模式：SANDBOX — cybqa.pesapal.com 上的测试付款 — 不会扣除真实款项。 或 LIVE — pay.pesapal.com 上的真实付款。 当当前模式的密钥缺失时会出现警告（请输入沙盒的 consumer key 和 secret — 在此之前，结账页面不会显示 Pesapal。，或正式环境的相同提示），当 Pesapal 不支持您店铺的默认货币时也会出现警告。如果没有修改扩展的权限，页面会显示设置但无法保存。

保存时，空的 Title 不会被接受：保留之前的标题并显示错误，其他字段仍会保存。Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，Geo Zone 和订单状态必须存在；否则该字段保留原值并显示错误。保存时会清除缓存的 Pesapal 访问令牌。

Pesapal

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Pesapal (M-Pesa, Airtel Money, cards)。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Sort Order：Pesapal 在结账时付款方式中的位置。留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 Pesapal。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的购物车金额（以店铺默认货币计算），达到后才会提供 Pesapal。留空则对任何金额都提供 Pesapal。

API 凭据

本部分说明如何获取密钥，并提供 cybqa.pesapal.com 和 pesapal.com 的链接。请分别在各自的字段中输入沙盒密钥和正式密钥。

Sandbox mode：Use the Pesapal sandbox (no real money)。开启后，新付款会使用沙盒密钥通过 cybqa.pesapal.com 处理。关闭后，将使用正式密钥在 pay.pesapal.com 上接受真实付款。默认：开启。

Sandbox consumer key：您的沙盒（演示）商户账户的 consumer key。仅在沙盒模式下使用。

Sandbox consumer secret：您的沙盒商户账户的 consumer secret。仅在沙盒模式下使用。

Live consumer key：来自您 Pesapal 商户后台的 consumer key。在关闭沙盒模式时使用。

Live consumer secret：来自您 Pesapal 商户后台的 consumer secret。在关闭沙盒模式时使用。

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

Clear saved consumer keys and secrets：保存了密钥后显示。勾选后点击 Save，即可删除全部四个已保存的密钥和 secret。

切换模式或更改密钥时，绝不会复用另一模式或其他密钥的访问令牌或通知 ID。在某一模式下发起的付款，即使切换模式之后，也始终在该模式下进行核对。

订单状态

OpenCart 在 Confirm Order 步骤创建订单时不设状态（缺失订单）。只有在 Pesapal 将付款报告为「Completed」之后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：Pesapal 确认付款时设置的状态。默认：Processing。

Pesapal Payment On Hold Status：金额或货币与订单不一致的付款，以及在订单取消后收到的付款。备注中会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：对于处于此状态（或退款状态）的订单，如果收到 Pesapal 付款，订单会被挂起，而不是被悄悄重新打开。默认：Canceled。

Refunded Status：当 Pesapal 报告订单付款已被冲正时设置。默认：Refunded。

付款通知（IPN）

IPN URL：显示您店铺的通知 URL。OpenCart 3 的格式类似 https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn，OpenCart 4 的格式类似 https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn，由您的 OpenCart 安装的前台地址生成。该 URL 会在首次付款时自动注册到 Pesapal，沙盒和正式环境分别注册，每个 consumer key 也分别注册，因此无需任何配置。首次付款后，本部分会显示 Registered IPN ID: 及 Pesapal 返回的 ID；在此之前，它会显示 尚未为当前模式和密钥注册。 该 URL 必须可以从互联网访问：其前面不能有防火墙或密码保护。店铺处于维护模式时它仍可正常工作，因为 OpenCart 允许付款扩展的请求通过（在 OpenCart 4 上，扩展为此添加了自己的启动动作，该动作同样允许顾客从 Pesapal 返回）。

高级

Debug log：将 Pesapal 请求和通知记录到 OpenCart 日志文件夹（storage/logs）中的 pesapal_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 pesapal_p_debug.old.log.php。即使开关关闭，错误和警告也始终会被记录。密钥、令牌和顾客数据绝不会被记录。默认：关闭。

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

Delete data：卸载扩展时删除扩展设置和日志。保存在订单中的 Pesapal 数据（跟踪 ID、备注）属于付款历史，始终保留。停用扩展不会删除任何内容。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。consumer key 和 secret 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 consumer key 和 secret 会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Pesapal (M-Pesa, Airtel Money, cards)）。在 Confirm Order 步骤中，顾客会看到您的描述。OpenCart 在此步骤创建订单，此时仍无状态。在 OpenCart 4 上，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一个 Pesapal 付款请求，并附上付款地址中的账单信息（在 OpenCart 4 上，如果结账不要求付款地址，则使用配送地址），然后将顾客引导至 Pesapal 付款页面。发送给 Pesapal 的付款描述为 Order、订单号和店铺名称。顾客可在该页面使用 Pesapal 提供的方式付款，例如 M-Pesa、Airtel Money、MTN、银行卡或银行转账。订单上的一条备注会记录该付款请求。

只有在 Pesapal 确认后，订单才会被标记为已付款。Pesapal 的通知和顾客返回时都不包含付款数据或签名，因此扩展不信任它们：对于每一次通知或返回，扩展都会以付款发起时所用的模式，通过经过身份验证的服务器到服务器请求向 Pesapal 查询交易状态。扩展还会检查该交易是否属于此订单，以及已付金额和货币是否与订单一致。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。

移动支付（mobile money）付款可能需要一些时间。如果顾客返回时 Pesapal 尚未确认付款，将显示 Payment confirmation 页面，内容为 Pesapal 正在确认您的付款。付款确认后，您将收到一封电子邮件 — 无需再次付款。，并带有 Check again 和 Back to checkout 按钮。Pesapal 的通知会在付款确认后立即设置订单状态。如果订单已被挂起，成功页面会显示 您的付款已收到，店铺正在审核。订单确认后，您将收到一封电子邮件。 当后续付款将订单从挂起状态改为已付款状态时，顾客会收到电子邮件通知。

如果顾客在 Pesapal 页面上取消付款，他会返回结账页面，并看到 Pesapal 付款已取消。您可以重试，或选择其他付款方式。 如果付款失败，提示为 Pesapal 付款未成功。请重试或选择其他付款方式。，订单上的备注会说明原因。购物车会被保留，顾客可以再次付款。在 OpenCart 4 上，这些消息显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，而 OpenCart 4 会更新结账中的订单，因此在新付款之前，扩展会向 Pesapal 检查该购物车之前的付款尝试：如果其中某次付款期间已被支付，则该订单会获得状态，顾客直接进入成功页面，而不会重复付款。之后在购物车较早的 Pesapal 页面上完成的付款仍会被接受。购物车的变更（包括新的数量）会被视为需要单独付款的新购物车。

OpenCart 4 会在结账页面保留订单，直到显示成功页面。如果该订单在此期间已被关闭（例如您取消了它），或者它是为较早的购物车付款且购物车之后已变更，顾客会被带回结账页面，并看到消息 您之前的订单已关闭。请重新确认订单：购物车将以新订单付款。 下一次 Confirm Order 将为新订单付款。已关闭的订单绝不会显示为已付款。

如果 Pesapal 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 Pesapal 暂时不可用。请稍后几分钟重试，或选择其他付款方式。、Pesapal 当前不可用。请选择其他付款方式。（密钥错误），或 Pesapal 无法发起付款：后跟 Pesapal 给出的原因。技术原因会写入日志和订单备注。订单总额必须大于零。

扩展在您自己的网站上没有付款表单（顾客始终在 Pesapal 页面付款），不支持保存银行卡，不支持订阅或定期付款，也不支持货币换算。

订单与退款

订单状态

无状态（缺失订单）：顾客已被引导至 Pesapal 但尚未付款、付款失败，或 Pesapal 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：Pesapal 将付款报告为 Completed，且金额和货币一致。备注会显示金额、付款方式、Pesapal 确认码和跟踪 ID。每笔付款只会被应用一次。

Pesapal Payment On Hold Status（默认 Pending）：已付金额或货币与订单不一致（备注 Pesapal amount/currency mismatch — held for review），或订单处于已取消或已退款状态时收到了款项。请在 Pesapal 后台核对该付款，然后完成订单或退款。

Refunded Status（默认 Refunded）：Pesapal 报告为订单付款的那笔付款已被冲正。对其他尝试的冲正只会记录在订单备注中。

如果对已付款的订单或购物车又完成了第二笔付款，订单不会改变。已付款订单上的备注会要求您在 Pesapal 后台退还第二笔付款。已取消和已退款的订单绝不会被自动重新打开。

备注是订单 History 中的条目，顾客看不到。

VibeFox Pesapal Pay Gateway tab

在 Sales > Orders 中打开一个通过 Pesapal 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的 VibeFox Pesapal Pay Gateway 标签页会显示带有 Sandbox 或 Live 标签的跟踪 ID、商户参考号、Pesapal 状态、付款方式、确认码、请求金额和已付金额、审核原因、订单的所有 Payment attempts（如果不止一次）以及 Payment notes。该标签页为只读，仅对有权访问该扩展的用户显示。

退款

扩展不会向 Pesapal 发送退款。请在 Pesapal 后台退还付款，然后在 OpenCart 中手动记录退款。Sales > Returns 中的商品退货不会通过 Pesapal 退还款项。

许可证密钥

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

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

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

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

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

故障排除

结账时不显示 Pesapal：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 consumer key 和 secret 是否已输入（沙盒模式为 Sandbox consumer key 和 Sandbox consumer secret，正式模式为 Live consumer key 和 Live consumer secret），以及订单货币是否为 KES、UGX、TZS、ZMW、RWF 或 USD。设置顶部的警告会指明问题。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Pesapal 的通知未能到达您的店铺，并且顾客也没有返回。请检查 IPN URL 中显示的 URL 能否从互联网访问（其前面不能有防火墙或密码保护）。开启 Debug log，并查看扩展页面上的 Log 字段。

店铺如何响应通知：已处理的通知会以 HTTP 200 响应。如果扩展无法处理，则会返回错误，Pesapal 稍后会重新发送该通知：400（跟踪 ID 缺失或格式错误）、404（本店铺没有任何订单使用该跟踪 ID）、409（该交易属于另一个商户参考号；不做任何更改）、502（当时无法访问 Pesapal API，或付款发起时所用模式的密钥缺失）以及 503（订单正在因顾客返回而被同时处理，或无法设置订单状态）。

顾客看到「Pesapal is not available at the moment」：Pesapal 拒绝了当前模式的 consumer key 或 secret。请检查密钥是否与模式相符：沙盒密钥仅适用于沙盒，正式密钥仅适用于正式模式。日志会显示 Pesapal 的错误。

顾客看到「Pesapal is temporarily unavailable」：无法连接 Pesapal，或无法注册通知 URL。请查看日志并重试。

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

顾客看到「We could not verify the Pesapal payment」：来自 Pesapal 的返回链接与店铺中的任何订单都不匹配。如果已扣款，请在 Pesapal 后台查找该付款，并在顾客再次付款之前核对订单。

切换模式后，旧模式的付款未被确认：付款会使用其发起时所在模式的密钥进行核对。请保留该模式的密钥，直到其付款被确认。

付款后订单处于挂起状态：请阅读 VibeFox Pesapal Pay Gateway 标签页中的备注。已付金额或货币与订单不一致，或付款是在订单取消之后到达的。请在 Pesapal 后台核对该付款，然后处理订单或退款。

对于开发者：扩展会触发 OpenCart 事件 pesapal_p_supported_currencies（货币列表）和 pesapal_p_submit_order_payload（发送给 Pesapal 之前的付款请求）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Pesapal Pay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 订单状态部分中的订单状态，重新安装时它们会恢复为默认值。扩展的 OpenCart 事件、缓存的 Pesapal 访问令牌和已注册的通知 ID 也总会被删除。在 OpenCart 4 上，还会删除其事件，以及在维护模式下允许通知和顾客返回通过的启动动作。如果 Delete data 已开启，其他设置（标题、描述、沙盒模式、密钥、调试日志开关）和日志也会被删除；如果关闭，它们会被保留，供以后重新安装时使用。Pesapal 付款尝试记录总会被保留。现有订单会保留其付款备注和 Pesapal 跟踪 ID。

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

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