VibeFox Pesapal for WooCommerce — 帮助
系统要求
WordPress: 6.2 或更高版本。
WooCommerce: 8.0 或更高版本，且已安装并启用。缺少 WooCommerce 时，插件拒绝启用。
PHP: 8.0 或更高版本。
Currency: 订单必须使用 KES、UGX、TZS、ZMW、RWF 或 USD。其他币种的订单在结账时不会显示此付款方式。订单以自身币种扣款；插件不进行币种转换。金额以主要货币单位发送，按币种精度四舍五入（UGX 和 RWF 不带小数）。
Pesapal account: 您需要 Pesapal 商户账户的消费者密钥和消费者密钥机密。测试和正式密钥不同。测试密钥来自 cybqa.pesapal.com 上的演示商户账户（Pesapal 也在开发者门户发布演示密钥）。正式密钥来自您的 Pesapal 商户控制面板。无需在 Pesapal 控制面板进行其他配置：插件会自行注册通知 URL。您的网站必须能从互联网访问，因为 Pesapal 会向其发送付款通知。
VibeFox license key: 在 vibefox.net 购买。一个密钥可用于一个域名。
安装
1. 在 WordPress 中转到 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。也可通过 FTP 将 wcp_pesapal_pay 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Pesapal > Manage，或在插件页面的插件名称下点击 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入测试消费者密钥和消费者密钥机密，启用 Enable/Disable，保存并创建测试订单。
6. 输入正式消费者密钥和消费者密钥机密，取消勾选 Sandbox mode 并保存，以接受真实付款。
配置
所有设置均在同一页面：WooCommerce > Settings > Payments > Pesapal。字段上方的标记显示当前模式：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 会被标为测试模式。
付款通知（IPN）
此区块显示店铺的通知 URL，形式为 https://your-site/wc-api/pesapal_pay/。首次付款时，URL 会自动向 Pesapal 注册，测试和正式环境以及每对密钥分别注册，因此无需配置。首次付款后，区块会显示 Registered IPN ID: 和 Pesapal 返回的 ID；此前显示 Not registered yet for the current mode and keys.。URL 必须能从互联网访问，不能被维护模式、防火墙或密码保护阻挡。
结账
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 商户控制面板中的消费者密钥机密。测试模式停用时使用。
切换模式或更改密钥时，绝不会复用另一模式或其他密钥的访问令牌或通知 ID。在某一模式中发起的付款始终在该模式中核查，即使之后切换模式也一样。
高级
Debug log: Log Pesapal requests and notifications 将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_pesapal_pay。错误和警告始终会记录。密钥、令牌和顾客数据绝不会记录。默认：关闭。
Delete data: Delete the plugin settings and logs when the plugin is deleted。保存在订单中的 Pesapal 数据（跟踪 ID、备注）属于付款历史，始终保留。停用插件绝不会删除任何内容。默认：关闭。
结账
顾客选择付款方式（默认为 Pesapal (M-Pesa, Airtel Money, cards)）并下单。在测试模式下，结账区块显示 Sandbox mode: no real money will be charged.。插件使用订单的账单信息，按订单币种为订单总额创建 Pesapal 付款请求，并添加包含模式、金额和 Pesapal 跟踪 ID 的订单备注。顾客被重定向至 Pesapal 付款页面，通过 Pesapal 提供的方式付款，例如 M-Pesa、Airtel Money、MTN、银行卡或银行。
只有 Pesapal 确认后，订单才会标记为已付款。Pesapal 通知和顾客返回请求不包含付款数据或签名，因此插件不会信任它们：每次都会在付款发起时的模式中，通过经身份验证的服务器间请求向 Pesapal 查询交易状态。还会核查交易是否属于此订单，以及已付金额和币种是否与订单一致。
付款后，顾客返回订单已收到页面。移动钱包付款可能需要片刻。如果付款尚未确认，页面显示 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.。Pesapal 通知会在稍后完成订单。如果订单被设为保留，页面显示 Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.。
如果顾客在 Pesapal 页面取消付款，会返回 Pay for order 页面并看到 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 提供的原因。技术详情写入订单备注和日志。订单总额必须大于零。
此付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。
插件不在结账页面本身提供付款表单（顾客始终在 Pesapal 页面付款），也不支持保存银行卡、订阅或定期付款，以及币种转换。
订单和退款
订单状态
Pending payment: 顾客已被重定向至 Pesapal，但尚未付款，或 Pesapal 尚未确认付款。
Processing: Pesapal 报告付款已完成，且金额和币种一致。订单备注显示金额、付款方式、Pesapal 确认码和跟踪 ID。订单交易 ID 即 Pesapal 跟踪 ID。每笔付款仅应用一次。
On hold: 已付金额或币种与订单不同（备注 Pesapal amount/currency mismatch — held for review），或款项对应的订单在付款前已被取消。请在 Pesapal 控制面板核查付款，然后完成订单或退款。
Failed: Pesapal 报告最近一次付款尝试失败。备注中会提供 Pesapal 的原因。如果顾客从 Pay for order 页面重试且再次失败，会再添加一条说明原因的备注。较早尝试的失败不会更改订单。顾客可以再次付款。
Refunded: Pesapal 报告已支付该订单的那笔付款被冲正。其他尝试被冲正时，只会在订单中记录备注。
如果已付款订单的第二次付款尝试也成功完成，订单不会更改。备注会要求您在 Pesapal 控制面板退还第二笔付款。已取消和已退款的订单绝不会自动重新开启。
退款
插件不会向 Pesapal 发送退款。请在 Pesapal 控制面板退款，然后在 WooCommerce 中手动记录退款。
许可证密钥
插件使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Pesapal 顶部。将密钥粘贴到 License key 并点击 Activate。区块会显示状态，例如许可证有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一密钥，使用 Remove key 从此网站移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥可用于一个域名。从网站移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放名额。
没有有效密钥时，顾客结账时不会看到 Pesapal。如果仍发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍能看到此付款方式，标记为 (unlicensed — visible to admins only)，以便您在购买密钥前配置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已经发起的付款仍会通过 Pesapal 通知和顾客返回得到确认。
许可证到期后，插件会继续工作，但更新和支持需要续订。系统会自动在后台重新检查状态。
故障排除
结账时未显示 Pesapal：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的消费者密钥和消费者密钥机密是否已填写（测试模式下为 Sandbox consumer key 和 Sandbox consumer secret，正式模式下为 Live consumer key 和 Live consumer secret），以及订单币种是否为 KES、UGX、TZS、ZMW、RWF 或 USD。设置顶部的警告会指出问题。开发者可以通过 pesapal_p_supported_currencies 过滤器更改币种列表。
付款成功，但订单仍为待付款：Pesapal 通知未到达您的店铺，且顾客没有返回。请检查 Payment notifications (IPN) 中显示的 URL 是否能从互联网访问（/wc-api/pesapal_pay/ 前不能有维护模式、防火墙或密码保护）。请查看 WooCommerce > Status > Logs，来源为 wcp_pesapal_pay。
店铺如何响应通知：处理成功的通知返回 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 控制面板核查付款，然后处理订单或退款。
许可证区块显示错误：请按区块中的消息操作。例如，密钥已在其他域名使用时，请在 vibefox.net 账户中释放一个名额，再点击 Check now。如果网站地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会按最后已知状态继续工作。
卸载
停用插件会保留全部数据。要移除插件，请在 Plugins 页面停用并删除。此插件的许可证密钥和许可证状态、缓存的 Pesapal 访问令牌以及已注册的通知 ID 始终会被移除。只有启用过 Delete data 时，才会移除插件设置和日志（包括轮转日志在内的日志文件，以及来源 wcp_pesapal_pay 的数据库日志记录）。否则，它们会保留以供日后重新安装使用。现有订单保留付款备注、交易 ID 和 Pesapal 跟踪 ID。
Pesapal 是其各自所有者的商标。本插件与 Pesapal 无关联，也未获得 Pesapal 认可。