VibeFox PayMongo for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法启用。

PHP：8.0 或更高版本。

货币：菲律宾比索（PHP）。当商店货币，或 Pay for order 页面上的订单货币不是 PHP 时，该付款方式会被隐藏。

PayMongo 账户：您需要 PayMongo 账户的 API 私钥，并且每种模式都需要一个 webhook（参见配置）。插件只使用私钥（sk_test_...、sk_live_...）和 webhook 签名密钥（whsk_...）。不需要公钥，因为支付页面由 PayMongo 托管。您提供的付款方式必须已在您的 PayMongo 账户中启用。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_paymongo_payment_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > PayMongo > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 粘贴您的 PayMongo 私钥，创建 webhook，并粘贴其签名密钥（参见配置）。

6. 选择付款方式，开启 Enable/Disable 并保存。在开启 Test mode 的情况下测试一次付款，然后再关闭它。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > PayMongo。页面会在字段上方提醒您：商店货币不是 PHP，当前模式没有私钥（此时 PayMongo 不会在结账时显示），或没有 webhook 密钥（此时仅在顾客返回时确认付款）；开启测试模式时还会显示 Test mode is on: no real payments are made. 在付款方式列表中，PayMongo 会被标记为需要设置，直到当前模式具有私钥为止。

常规

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

Title：顾客在结账时看到的付款方式名称。默认：PayMongo (Card, GCash, GrabPay, Maya)。

Description：结账时显示在付款方式下方的文字。默认：You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods：PayMongo 结账页面上提供的付款方式。请只选择您 PayMongo 账户中已启用的方式，否则 PayMongo 会拒绝结账。默认：Cards, GCash, GrabPay and Maya。

API 密钥

从 PayMongo Dashboard > Developers > API keys 复制私钥。不需要公钥。每个密钥都必须以预期的前缀开头。前缀错误的值不会被保存：页面会显示该字段 must start with 对应前缀，并显示 The previous value was kept.

Test mode：Enable test mode (no real payments)。新付款使用测试密钥。之前的付款保留其发生时的模式，因此状态检查和退款会使用匹配的密钥。默认：开启。关闭它即可接受真实付款。

Test secret key：测试模式的私钥。以 sk_test_ 开头。

Test webhook secret：测试模式 webhook 的签名密钥。以 whsk_ 开头。

Live secret key：正式模式的私钥。以 sk_live_ 开头。

Live webhook secret：正式模式 webhook 的签名密钥。以 whsk_ 开头。

Webhook

Webhook 会告知您的商店付款已完成，即使顾客在付款后关闭了浏览器也是如此。请在 PayMongo 控制面板（或通过 PayMongo API）为每种模式（测试和正式）创建一个 webhook，URL 使用设置中本部分显示的地址。它类似 https://your-site/?wc-api=paymongo_p_webhook。

请选择以下事件：

将每个 webhook 的签名密钥（whsk_...）复制到 Test webhook secret 或 Live webhook secret 中。没有有效签名的 webhook 会被拒绝，并且事件的模式必须与签名的模式一致。在修改订单之前，每个事件都会通过 PayMongo API 再次核实。PayMongo 会将整个账户的事件发送到每个 webhook；非本商店创建的付款事件将被忽略。如果没有 webhook，付款只会在顾客返回您的商店时确认。

订单

付款后的订单状态：付款成功后设置的订单状态。状态会立即设置，不会再有第二次状态变更。

高级

Debug log：Log API calls and webhook events 会将它们写入 WooCommerce > Status > Logs，来源为 wcp_paymongo_payment_gateway。错误始终会被记录。密钥和顾客数据从不记录。默认：关闭。

Delete data on uninstall：Delete the settings and logs when the plugin is deleted。订单上保存的 PayMongo ID 会被保留，因为退款和财务核算需要它们。默认：关闭。

结账

顾客选择付款方式（默认为 PayMongo (Card, GCash, GrabPay, Maya)）并提交订单。在测试模式下，结账页面会显示 Test mode: no real payment will be made. 插件会以 PHP 为单位，为订单总额创建一个 PayMongo 结账会话，其中包含一行 Order # 和订单编号，然后将顾客带到 PayMongo 结账页面。顾客的姓名、电子邮件、电话和账单地址会传递给 PayMongo。顾客在那里选择其中一种付款方式并付款。

该付款方式仅对至少 ₱100.00 的订单显示。低于此金额的订单无法通过 PayMongo 付款。

付款后，顾客会返回您商店的订单接收页面。只有 PayMongo 确认后，订单才会被标记为已付款：插件会在顾客返回时以及 webhook 到达时向 PayMongo API 查询付款情况。如果 PayMongo 仍在处理付款或无法连接，顾客仍会进入订单接收页面，之后由 webhook 完成订单。

如果顾客在 PayMongo 页面取消或未完成付款，他会进入 Pay for order 页面，并看到消息 You cancelled the PayMongo payment. You can try again or choose another payment method. 或 Your PayMongo payment was not completed. You can try again or choose another payment method. 订单保持未付款状态。新的尝试会先检查之前的付款：如果期间已付款，则在不再次付款的情况下完成订单；否则之前的 PayMongo 结账链接会过期，因此顾客无法付款两次。在之前的付款仍在处理时，顾客会看到 Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

如果 PayMongo 无法启动付款，顾客会看到一条简短消息，例如 The payment could not be started. Please try again or choose another payment method. 或 PayMongo could not be reached. Please try again in a moment. 技术原因会添加到订单备注中。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。

插件仅在 PayMongo 页面上接受一次性付款。您自己的结账页面上没有银行卡输入框，也不支持保存银行卡、订阅或定期付款、分期付款，以及分开的授权与扣款。

订单和退款

订单状态

Pending payment：顾客已被带到 PayMongo 但尚未付款，或 PayMongo 尚未确认付款。备注中会记录为订单创建的每个 PayMongo 结账。PayMongo 正在处理付款时，备注会说明这一点。

Processing 或 Completed：付款已确认。状态遵循 Order status after payment 的设置。订单备注会显示 PayMongo 付款、金额、方式和模式。交易 ID 即 PayMongo 付款 ID（pay_...）。订单页面会在账单地址下方显示 PayMongo 结账会话、付款意图和模式。

On hold：付款金额或货币与订单不符（备注 amount/currency mismatch）；或者商店处于正式模式时收到了测试模式的付款，因此没有收到任何款项；或者订单被取消（例如库存保留超时）之后才收到付款。订单备注会说明原因。请检查订单，并进行处理或退款。

Failed：已签名的 payment.failed webhook 报告，待付款订单的最近一次付款尝试失败。备注会显示 PayMongo 的失败代码和消息。顾客可以重新付款。

如果已付款的订单又收到第二笔付款（例如通过旧的结账链接），订单不会改变。备注会要求您在 PayMongo 控制面板中退还重复的付款。已付款后被取消或退款的订单绝不会被重新打开。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via PayMongo (Card, GCash, GrabPay, Maya)（按钮会显示您的付款方式标题）。支持全额和部分退款。退款会使用付款所在模式（测试或正式）的私钥发送，因此该私钥必须已设置。如果 PayMongo 不接受退款，WooCommerce 会显示错误，并且不会记录退款。成功的退款会连同 PayMongo 退款 ID 和状态一起添加到订单备注中。

在 PayMongo 控制面板中进行的退款不会同步到 WooCommerce。请从 WooCommerce 订单中退款，或在 WooCommerce 中创建手动退款。

许可证密钥

插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > PayMongo 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 PayMongo。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的商店管理员仍可看到该付款方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。

许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时没有显示 PayMongo：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式是否有私钥（测试模式为 Test secret key，正式模式为 Live secret key），商店货币是否为 PHP，以及订单总额是否至少为 ₱100.00。开发者可以使用 paymongo_p_minimum_amount 过滤器修改最低金额。

付款已完成，但订单仍为 Pending payment：webhook 未正常工作，并且顾客没有返回商店。请在 PayMongo 控制面板中检查您所用模式下是否存在 webhook，其 URL 是否与设置中显示的完全一致，以及三个事件是否都已选中。检查其签名密钥是否位于对应字段中（Test webhook secret 或 Live webhook secret）。

Webhook 返回 Invalid signature：该模式的签名密钥缺失，或属于另一个 webhook。请将 webhook 的签名密钥粘贴到其对应模式的字段中。

Webhook 返回 Mode mismatch：测试事件被签为正式模式，或相反。请检查每个 webhook 是否属于正确的模式。

Webhook 返回 Temporary error：无法通过 PayMongo API 核实付款，或订单在同一时刻正被另一个请求处理。PayMongo 会自动重试 webhook。

值未保存：密钥被粘贴到了错误的字段中。私钥以 sk_test_ 或 sk_live_ 开头，webhook 密钥以 whsk_ 开头。

顾客下单时出现错误：请打开订单备注或查看 WooCommerce > Status > Logs，来源为 wcp_paymongo_payment_gateway。错误的私钥会显示该付款方式暂时不可用的消息。未在您的 PayMongo 账户中启用的付款方式会导致 PayMongo 拒绝结账；请将其从 Payment methods 中移除。

正式商店中的测试付款：商店处于正式模式时收到的测试付款，会使订单进入保留状态，并附带一条说明未收到款项的备注。即使之后切换回测试模式，真实付款仍会被正确识别，并使用正式私钥退款。

付款后订单处于 On hold：请阅读订单备注。付款金额或货币与订单不符，付款是测试付款，或付款是在订单取消之后到达的。请处理订单或退还付款。

退款因模式相关消息而失败：付款是在测试或正式模式下完成的，而该模式的私钥未设置。请输入该私钥后重试。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态工作。

卸载

停用插件会保留所有数据。要删除插件，请在 Plugins 页面中先停用再删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete data on uninstall 时，网关设置、临时数据和日志才会被删除；否则它们会保留，以便之后重新安装。现有订单会保留其付款备注、交易 ID 和 PayMongo ID。

PayMongo 是其各自所有者的商标。本插件与 PayMongo 无关联，也未获得 PayMongo 的认可。