VibeFox PayMongo for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
货币：菲律宾比索（PHP）。只有当顾客以 PHP 付款且总额至少为 ₱100.00 时，结账页面才会显示 PayMongo。如果您的店铺还没有该货币，请在 System > Localisation > Currencies 中添加。如果店铺的默认货币不是 PHP，设置页面会发出警告，顾客必须切换为 PHP 才能看到 PayMongo。
PayMongo 账户：您需要 PayMongo 账户的密钥 API，以及每种模式各一个 Webhook（参见“配置”）。仅使用密钥（sk_test_...、sk_live_...）和 Webhook 签名密钥（whsk_...）。不需要公开密钥，因为付款页面由 PayMongo 托管。您提供的付款方式必须已在您的 PayMongo 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_paymongo_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_paymongo_payment_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paymongo_payment_gateway-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayMongo Payment Gateway，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。在页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见“许可证密钥”）。
4. 粘贴您的 PayMongo 密钥，在 PayMongo 中创建 Webhook，并粘贴其签名密钥（参见“配置”）。
5. 选择付款方式，开启 Enable/Disable，然后点击 Save。在 Test mode 开启的情况下测试一笔付款，然后关闭它。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paymongo_payment_gateway.ocmod.zip。请不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayMongo Payment Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 请按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、PayMongo 密钥、Webhook 和付款方式。两个版本的设置页面及其字段相同。只有 Webhook URL 不同（参见“Webhook”）。
新安装默认关闭付款方式，并开启测试模式。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox PayMongo Payment Gateway > Edit。各部分列于左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当店铺的默认货币不是 PHP、当前模式没有密钥（此时结账时不显示 PayMongo）或没有 Webhook 签名密钥（此时只有顾客返回店铺后才会确认付款）时，页面会发出警告；测试模式开启时，页面会显示 Test mode is on: no real payments are made.
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，所选的地理区域和订单状态必须存在；否则不会保存任何内容，并且页面会指出相应字段。前缀错误的密钥不会被保存，但其他字段会被保存（参见“API 密钥”）。
PayMongo
Enable/Disable：Enable PayMongo 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PayMongo (Card, GCash, GrabPay, Maya)。必填，最多 128 个字符。
Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods：PayMongo 付款页面提供的方式。请只选择已在您的 PayMongo 账户中启用的方式，否则 PayMongo 会拒绝结账。如果未选择任何方式，则使用默认值。默认：Cards、GCash、GrabPay 和 Maya。
Sort Order：PayMongo 在结账时付款方式中的位置。留空或输入整数。
Geo Zone：仅为所选地理区域内的付款地址提供 PayMongo。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单在店铺默认货币下必须达到的结账总额，才会提供 PayMongo；此外还须满足 PayMongo 的 ₱100.00 最低金额。留空则不设额外最低金额。
API 密钥
从 PayMongo Dashboard > Developers > API keys 复制密钥（那里有指向该部分的链接）。不需要公开密钥。每个密钥都必须以预期的前缀开头。前缀错误的值不会被保存，例如在测试字段中填入正式密钥：页面会显示该字段必须以该前缀开头，并显示 The previous value was kept.
Test mode：Enable test mode (no real payments)。新付款使用测试密钥。之前的付款会保留其发生时所处的模式，因此状态查询和退款会使用对应的密钥。默认：开启。关闭后才会接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real payment will be made.
Test secret key：测试模式的密钥。以 sk_test_ 开头。
Test webhook secret：测试模式 Webhook 的签名密钥。以 whsk_ 开头。
Live secret key：正式模式的密钥。以 sk_live_ 开头。
Live webhook secret：正式模式 Webhook 的签名密钥。以 whsk_ 开头。
已保存的密钥和签名密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。
Webhook
即使顾客在付款后关闭浏览器，Webhook 也会告知您的店铺已完成付款。请在 PayMongo Dashboard（或通过 PayMongo API）为测试和正式两种模式各创建一个 Webhook，URL 使用本部分 Webhook URL 中显示的地址。在 OpenCart 3 中格式类似：https://your-store/index.php?route=extension/payment/wcp_paymongo_payment_gateway/webhook，在 OpenCart 4 中为：https://your-store/index.php?route=extension/wcp_paymongo_payment_gateway/payment/wcp_paymongo_payment_gateway.webhook，由您 OpenCart 安装的店铺地址生成。请完全按照设置中显示的样子复制该 URL。
选择以下事件（它们也列在本部分中）：
将每个 Webhook 的签名密钥（whsk_...）复制到 Test webhook secret 或 Live webhook secret 中。签名无效的 Webhook 会被拒绝。签名使用其所属模式的密钥进行验证，事件的模式必须与之匹配，因此测试 Webhook 永远不会确认正式付款。在修改订单之前，每个事件都会使用该付款模式的密钥再次通过 PayMongo API 验证。不是在本店铺发起的付款所产生的事件会被忽略。如果没有 Webhook，只有顾客在付款后返回店铺时，订单才会被确认。
订单
OpenCart 在 Confirm Order 步骤创建订单，此时不带状态（即缺失订单）。只有在 PayMongo 确认付款后，订单才会获得状态。OpenCart 没有 On hold 状态：默认情况下，等待状态和搁置状态都是待付款（Pending），PayMongo 选项卡和订单备注可以区分二者。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。下方每个字段都会列出您的 OpenCart 订单状态。
Order status after payment：付款成功后设置的状态。默认：处理中。Complete 适合无需配送的虚拟或可下载商品。
Awaiting PayMongo payment：顾客已在 PayMongo 页面完成操作，但付款仍在处理中（例如网银付款）。Webhook 或下一次检查会完成订单。默认：待付款。
PayMongo payment on hold：金额或币种不符、正式店铺中的测试付款，或订单取消后才到达的付款。备注会说明原因。默认：待付款。
Failed status：等待中的付款之后失败（payment.failed）。对于没有状态的订单，失败的尝试会使其仍然没有状态，顾客可以再次付款。默认：失败。
Cancelled status：您为已取消订单设置的状态。之后到达的付款会使订单进入搁置状态，而不是完成订单。默认：已取消。
Refunded status：在订单选项卡中全额退款后设置。默认：已退款。
高级
Debug log：将 PayMongo API 调用和 Webhook 事件记录到 OpenCart 日志文件夹（storage/logs）中的 paymongo_p_debug.log.php。该文件无法通过网页打开。即使开关关闭，错误和警告也始终会被记录。密钥和顾客数据永远不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。为订单和退款保存的 PayMongo ID 始终保留，因为退款和会计需要它们。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤，顾客选择付款方式（默认为 PayMongo (Card, GCash, GrabPay, Maya)）。在 Confirm Order 步骤，顾客会看到您的描述以及备注 After you confirm the order you will be redirected to PayMongo to complete the payment. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。
顾客点击 Confirm Order 后，扩展会以 PHP 为订单总额创建一个 PayMongo 结账会话（Checkout Session），其中包含一行 Order # 和订单号，然后将顾客带到 PayMongo 付款页面。顾客的姓名、电子邮件、电话和账单地址会传递给 PayMongo。顾客在那里选择一种已选定的方式并付款。订单中的一条备注会记录该 PayMongo 结账。
付款后，顾客返回您的店铺。只有在 PayMongo 确认后，订单才会被标记为已付款：扩展会在顾客返回时以及 Webhook 到达时向 PayMongo API 查询付款情况。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，并显示 Your PayMongo payment has been received. 如果顾客返回时 PayMongo 仍在处理付款，订单会获得等待状态，页面会显示 PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. 对于搁置的订单，页面会显示 Your payment was received and is being reviewed. We will update your order shortly. 如果顾客返回时无法连接 PayMongo，Payment confirmation 页面会显示 Your payment is being confirmed by PayMongo. You will receive an e-mail as soon as it is confirmed — please do not pay again. 并附带 Check again 按钮；Webhook 一到达就会设置订单状态。当订单从等待状态变为已付款或付款失败状态时，顾客会收到 OpenCart 常规的订单状态邮件。
如果顾客在 PayMongo 页面取消或没有完成付款，他会返回结账页面，并显示 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. 购物车会被保留。在 OpenCart 4 中，这些消息会显示在结账页面上方。新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 则更新结账的订单）会先检查之前的付款：如果此期间已付款，则直接确认付款，无需再次付款；否则之前的 PayMongo 付款链接会过期，因此同一购物车无法被重复支付。在之前的付款仍在处理期间，顾客会看到 Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again. 如果同一购物车中的另一个订单已付款或正在等待付款，顾客会被带到成功页面。同一购物车中的变更，包括新的数量，会被视为需要单独付款的新购物车。
OpenCart 4 会将订单保留在结账中，直到显示成功页面。如果该订单期间已被关闭（例如您取消了它），或者它是为另一个购物车付款的，顾客会被带回结账页面，并显示 Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. 下一次 Confirm Order 会支付一个新订单。已付款的订单绝不会显示为对另一个购物车已付款。
如果 PayMongo 无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方会显示简短的提示，例如 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. 技术原因会写入日志。
即使店铺处于维护模式，Webhook 仍然有效，因为 OpenCart 允许付款扩展的请求通过（在 OpenCart 4 中，扩展为此添加了自己的启动操作，这也允许顾客从 PayMongo 返回）。
本扩展仅在 PayMongo 页面接受一次性付款。您自己的结账页面没有银行卡输入栏，不支持保存银行卡、订阅或定期付款、分期付款，也不支持单独的授权和扣款。
订单与退款
订单状态
无状态（缺失订单）：顾客已被带到 PayMongo 但尚未付款，或 PayMongo 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。
付款后的订单状态（默认处理中）：付款已确认。备注会显示 PayMongo 付款、金额、方式、模式以及确认方式（Webhook、返回或付款重试）。
PayMongo 付款等待中（默认待付款）：顾客在 PayMongo 仍在处理付款时返回。PayMongo 确认后，订单会转为已付款状态。
PayMongo 付款搁置（默认待付款）：已付金额或币种与订单总额不符；或者店铺处于正式模式时付款是在测试模式下完成的，因此没有收到任何款项；或者付款是在订单取消后到达的。备注会说明原因。请核对订单，并处理订单或退还付款。
失败状态（默认失败）：一条已签名的 payment.failed Webhook 报告了等待中订单的最近一次付款尝试失败。备注会显示 PayMongo 的失败代码和消息。如果同一笔付款之后成功，订单会转为已付款状态。
已退款状态（默认已退款）：付款已通过扩展全额退款。
如果已付款的订单，或已付款购物车中的另一个订单又收到了第二笔付款，已付款的订单不会被更改。备注会要求您在 PayMongo Dashboard 中退还这笔重复付款。已付款并随后取消或退款的订单永远不会被重新打开。
备注是订单 History 中的条目，顾客看不到。
VibeFox PayMongo Payment Gateway 选项卡
在 Sales > Orders 中打开一笔通过 PayMongo 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox PayMongo Payment Gateway 选项卡会显示 PayMongo payment、PayMongo payment intent、PayMongo checkout、PayMongo mode（测试付款会带有 Test mode 标签）、Status、Paid / refunded 金额、退款表单、退款记录以及订单的 Notes。该选项卡会显示给有权访问本扩展的用户。
退款
在 VibeFox PayMongo Payment Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），还可以选填 Reason (optional)，然后点击 Refund via PayMongo。确认提示 Refund this amount through PayMongo? This cannot be undone. 支持全额和部分退款，最多两位小数。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额受 PayMongo 实际收取金额的限制，因此在金额不符之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款使用付款时所用模式（测试或正式）的密钥发送，因此必须设置该密钥。如果 PayMongo 不接受退款，选项卡会显示错误，并且不会记录任何退款。成功的退款会添加到退款记录和备注中，并附带 PayMongo 退款 ID 和状态。全额退款会将订单设置为 Refunded status，不会通知顾客，也不会把商品退回库存，与手动更改状态相同。部分退款不会更改状态。
Sales > Returns 中的商品退货不会通过 PayMongo 退还款项。在 PayMongo Dashboard 中完成的退款不会同步到 OpenCart。请改为在订单选项卡中退款，或手动更新订单。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayMongo Payment Gateway 是 Extensions > Extensions > Payments > VibeFox PayMongo Payment Gateway > Edit 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏部分字符的形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），还有以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方有 Product: opencart-payment-paymongo 一行，以及打开您 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 PayMongo。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试本扩展。在 OpenCart 4 上没有此预览功能：店铺看不到管理员登录，因此没有有效密钥时，该付款方式会对所有人隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可关闭它，并隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款仍可正常进行。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 PayMongo：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否设置了密钥（测试模式为 Test secret key，正式模式为 Live secret key）、顾客是否以 PHP 付款，以及总额是否至少为 ₱100.00。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。
付款已完成，但订单仍无状态：Webhook 未正常工作，且顾客没有返回店铺。请在 PayMongo Dashboard 中检查您所用模式下是否存在 Webhook，其 URL 是否与 Webhook URL 中显示的完全一致，以及三个事件是否都已选中。检查其签名密钥是否位于对应字段中（Test webhook secret 或 Live webhook secret）。
Webhook 返回 Invalid signature：该模式的签名密钥缺失，或属于另一个 Webhook。请将该 Webhook 的签名密钥粘贴到其模式对应的字段中。
Webhook 返回 Mode mismatch：测试事件被按正式模式签名，或反之。请检查每个 Webhook 是否属于正确的模式。
Webhook 返回 Temporary error：无法通过 PayMongo API 检查付款，例如付款模式的密钥缺失。PayMongo 会自动重试该 Webhook。
Webhook 返回 Busy, retry：订单在同一时刻正被另一个请求确认，或无法设置订单状态。PayMongo 会自动重试该 Webhook。原因记录在 Log 中。
Webhook 返回 Ignored：该事件属于未在本店铺发起的付款，或属于其他模式。不会有任何更改。
在浏览器中打开 Webhook URL 时显示 Method not allowed：这是正常的。该 URL 只接受来自 PayMongo 的请求。
值未能保存：密钥粘贴到了错误的字段中。密钥以 sk_test_ 或 sk_live_ 开头，Webhook 签名密钥以 whsk_ 开头。
顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段。密钥错误会显示付款方式暂时不可用的消息。未在您的 PayMongo 账户中启用的付款方式会导致 PayMongo 拒绝结账；请将其从 Payment methods 中删除。This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不再匹配，或付款方式在此期间已被关闭。
正式店铺中的测试付款：店铺处于正式模式时收到的测试付款，会使订单进入搁置状态，并附带备注说明没有收到任何款项。真实付款始终会被识别，即使之后切换回测试模式也是如此，并会使用正式密钥退款。
付款后订单处于搁置状态：请阅读 VibeFox PayMongo Payment Gateway 选项卡中的备注（参见“订单状态”），然后处理订单或退还付款。
选项卡中没有退款表单：付款尚未确认、已全额退款，或您的用户组没有修改扩展的权限。
退款因模式相关的消息而失败：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入密钥后重试。
对开发者：在创建结账会话之前，扩展会触发 OpenCart 事件 paymongo_p_checkout_session_data，并附带会话数据和订单。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayMongo Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态；重新安装时这些设置会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件以及在维护模式下允许 Webhook 和顾客返回通过的启动操作）。如果 Delete data on uninstall 已开启，其余网关设置（标题、描述、付款方式、测试模式、密钥、Webhook 签名密钥、日志记录）以及日志都会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。订单和退款的 PayMongo ID 始终保留，因此之前已付款的订单即使在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PayMongo Payment Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
PayMongo 是其各自所有者的商标。本扩展与 PayMongo 无关联，也未获得 PayMongo 的认可。