VibeFox Pesapal for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。在较旧的 PHP 版本上，模块拒绝安装。
货币：购物车必须使用 KES、UGX、TZS、ZMW、RWF 或 USD。使用其他货币时，结账时将不显示该付款方式。购物车以其自身货币收费；模块不进行货币换算。金额以主货币单位发送，并按该货币的精度取整（UGX 和 RWF 没有小数位）。
Pesapal 账户：您需要 Pesapal 商户账户的消费者密钥和消费者密钥机密。测试和正式环境的密钥各不相同。测试密钥来自 cybqa.pesapal.com 上的演示商户账户（Pesapal 也会在其开发者门户上公布演示密钥）。正式密钥来自您的 Pesapal 商户控制面板。除此之外，Pesapal 控制面板中无需任何其他设置：模块会自行注册其通知 URL。您的店铺必须可以从互联网访问，因为 Pesapal 会向它发送付款通知。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Pesapal Pay Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
4. 输入测试消费者密钥和消费者密钥机密，开启 Enable/Disable，点击 Save，然后下一笔测试订单。
5. 输入正式消费者密钥和消费者密钥机密，关闭 Sandbox mode，然后点击 Save，即可接受真实付款。
安装时，模块会创建订单状态 Pesapal payment on hold。PrestaShop 会为所有货币、国家和客户群组启用新的付款模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure。每个部分都有自己的 Save 按钮，该按钮会保存整个页面。字段上方的标签显示当前模式：SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. 或 LIVE — Real payments on pay.pesapal.com. 当当前模式的密钥缺失（Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout.，或正式模式的同样提示）以及 Pesapal 不支持您店铺的默认货币时，会显示警告。
Pesapal
Enable/Disable：Enable Pesapal 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Pesapal (M-Pesa, Airtel Money, cards)。必填：不会保存空标题，将保留之前的标题。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.
API 凭据
本部分说明如何获取密钥，并提供 cybqa.pesapal.com 和 pesapal.com 的链接。请分别在各自的字段中输入测试和正式密钥。
Sandbox mode：Use the Pesapal sandbox (no real money)。开启后，新付款将使用测试密钥通过 cybqa.pesapal.com 处理。关闭后，将使用正式密钥在 pay.pesapal.com 上接受真实付款。默认：开启。
Sandbox consumer key：您的测试（演示）商户账户的消费者密钥。仅在测试模式下使用。
Sandbox consumer secret：您的测试商户账户的消费者密钥机密。仅在测试模式下使用。
Live consumer key：来自您的 Pesapal 商户控制面板的消费者密钥。在关闭测试模式时使用。
Live consumer secret：来自您的 Pesapal 商户控制面板的消费者密钥机密。在关闭测试模式时使用。
已保存的密钥和机密不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved consumer keys and secrets：勾选该选项并点击 Save，即可删除全部四个已保存的密钥和机密。
保存设置会丢弃缓存的 Pesapal 访问令牌。切换模式或更改密钥时，绝不会复用另一模式或其他密钥的访问令牌或通知 ID。在一种模式下发起的付款，即使切换后，也始终在该模式下进行核对。
付款通知（IPN）
IPN URL：显示您店铺的通知 URL。启用友好 URL 时，它类似于 https://your-shop/module/wcp_pesapal_pay/webhook，可能带有语言代码，例如 /en/。该 URL 会在首次付款时自动向 Pesapal 注册，测试和正式环境分别注册，且每对密钥各注册一次，因此无需进行任何配置。首次付款后，本部分会显示 Registered IPN ID: 以及 Pesapal 返回的 ID；在此之前，它会显示 Not registered yet for the current mode and keys. 该 URL 必须可以从互联网访问：其前面不能有防火墙或密码保护。店铺处于维护模式时它仍会正常工作，也不受店铺国家限制的影响。
高级
Debug log：Log Pesapal requests and notifications。将详细信息写入模块文件夹中的 logs/pesapal_p_debug.log.php。该文件无法通过网页打开。即使开关已关闭，错误和警告仍会始终记录。密钥、令牌和顾客数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete data：Delete the module settings and logs when the module is uninstalled。保存在订单中的 Pesapal 数据（跟踪 ID、备注）属于付款历史，始终会被保留。禁用模块不会删除任何内容。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Pesapal (M-Pesa, Airtel Money, cards)）并查看其说明。确认后，模块会以购物车货币为购物车总额创建 Pesapal 付款请求，并附上发票地址中的账单信息，然后将顾客带到 Pesapal 付款页面。发送给 Pesapal 的付款说明为 Cart、购物车编号和店铺名称。顾客可以在该页面使用 Pesapal 提供的方式付款，例如 M-Pesa、Airtel Money、MTN、银行卡或银行转账。此时尚未创建订单。
只有在 Pesapal 确认付款后，订单才会被标记为已付款。Pesapal 的通知和顾客的返回不包含付款数据，也没有签名，因此模块不会信任它们：对于每一个通知或返回，模块都会在付款发起时所处的模式下，通过经过身份验证的服务器间请求向 Pesapal 查询交易状态。模块还会检查该交易是否属于此购物车，以及已付金额和货币是否与购物车一致。之后才会创建订单，顾客将看到标准的订单确认页面。
移动支付可能需要一些时间。如果顾客返回时 Pesapal 尚未确认付款，将显示 Payment confirmation 页面，内容为 Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again.，并带有 Check again 和 Back to checkout 按钮。来自 Pesapal 的通知会在付款确认后立即创建订单。如果订单已被设为保留，确认页面将显示 Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.
如果顾客在 Pesapal 页面上取消，他将返回结账页面，并看到 The Pesapal payment was cancelled. You can try again or choose another payment method. 如果付款失败，提示为 The Pesapal payment was not successful. Please try again or choose another payment method. 购物车会保留，顾客可以再次付款。购物车的每次付款尝试都会被记录，因此即使之后的付款是在该购物车较早的 Pesapal 页面上完成的，也会被接受。
如果 Pesapal 无法发起付款，顾客将停留在结账页面，并显示简短提示，例如 Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method.、Pesapal is not available at the moment. Please choose another payment method.（密钥错误），或者 Pesapal could not start the payment: 后跟 Pesapal 给出的原因。技术原因会写入日志。订单总额必须大于零。
本模块不会在您自己的网站上提供付款表单（顾客始终在 Pesapal 页面付款），不支持保存银行卡、订阅或定期付款，也不进行货币换算。
订单和退款
订单状态
暂无订单：顾客已被转到 Pesapal 但尚未付款，付款失败，或 Pesapal 尚未确认付款。此时只存在购物车。
Payment accepted：Pesapal 报告付款已完成，且金额和货币一致。付款会以 Pesapal 跟踪 ID 作为交易 ID 进行记录，备注中显示金额、付款方式、Pesapal 确认码和跟踪 ID。每笔付款只会被应用一次。
Pesapal payment on hold：已付金额或货币与购物车不一致（备注 Pesapal amount/currency mismatch — held for review），或收到了已取消订单的付款。当实际付款金额与订单货币一致时，会记录在订单上。请在 Pesapal 控制面板中核对付款，然后完成订单或退款。
Refunded：Pesapal 报告用于支付该订单的付款已冲正。对其他尝试的冲正仅会记录在订单上。
如果已付款购物车的第二次付款尝试也完成了，订单不会改变。备注会要求您在 Pesapal 控制面板中退还第二笔付款。已取消和已退款的订单绝不会被自动重新打开。
Pesapal 付款区块
订单页面会显示一个 Pesapal payment 区块，带有 Sandbox 或 Live 标签，并显示跟踪 ID、商户参考号、Pesapal 状态、付款方式、确认码、请求金额和已付金额、需要审核的原因、购物车的全部 Payment attempts，以及订单的 Payment notes。该区块为只读。
退款
本模块不会向 Pesapal 发送退款。请在 Pesapal 控制面板中退款，然后在 PrestaShop 中手动记录退款。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Pesapal Pay Gateway 位于 Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure 页面的最顶部，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以隐藏部分字符的方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方是 Product: presta-payment-pesapal 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放该名额。
如果没有有效的密钥，结账时顾客将看不到 Pesapal。即使如此仍发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，关于现有付款（包括冲正）的 Pesapal 通知仍会被应用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Pesapal：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式的消费者密钥和机密是否已输入（测试模式为 Sandbox consumer key 和 Sandbox consumer secret，正式模式为 Live consumer key 和 Live consumer secret），以及购物车货币是否为 KES、UGX、TZS、ZMW、RWF 或 USD。设置页面顶部的警告会指出问题所在。在 Payment > Preferences 中，请检查该模块是否允许用于购物车货币、顾客所在国家和顾客群组。开发人员可以通过 actionPesapalSupportedCurrencies 钩子更改货币列表。
付款已完成，但未创建订单：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 拒绝了当前模式的消费者密钥或机密。请检查密钥是否与模式相符：测试密钥只能用于测试模式，正式密钥只能用于正式模式。日志会显示 Pesapal 的错误。
顾客看到 Pesapal is temporarily unavailable：无法连接 Pesapal，或无法注册通知 URL。请查看日志并重试。
切换后，旧模式的付款未被确认：付款使用发起该付款时所用模式的密钥进行核对。请保持该模式的密钥处于已输入状态，直到其付款得到确认。
付款后订单处于 Pesapal payment on hold 状态：请阅读 Pesapal payment 区块中的备注。已付金额或货币与购物车不一致，或付款是在订单取消之后到达的。请在 Pesapal 控制面板中核对付款，然后处理订单或退款。
卸载
进入 Modules > Module Manager，打开 VibeFox Pesapal Pay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。缓存的 Pesapal 访问令牌和已注册的通知 ID 始终会被删除。如果 Delete data 已开启，模块设置和日志也会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Pesapal 付款尝试和订单状态 Pesapal payment on hold 始终会被保留。现有订单会保留其付款备注、交易 ID 和 Pesapal 跟踪 ID。
Pesapal 是其各自所有者的商标。本模块与 Pesapal 无关联，也未获得 Pesapal 的认可。