ZH
EUR
返回

VibeFox PayMongo for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在更旧的 PHP 版本上。

货币：菲律宾比索（PHP）。PayMongo 仅在购物车为 PHP 货币时才会在结账时显示。如果您商店的默认货币不是 PHP，设置页面会向您发出警告，顾客也必须切换为 PHP 才能看到 PayMongo。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox PayMongo Payment Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 粘贴您的 PayMongo 私钥，在 PayMongo 中创建 webhook，并粘贴它们的签名密钥（参见配置）。

5. 选择付款方式，开启 Enable/Disable，然后点击 Save。在开启 Test mode 的情况下测试一笔付款，然后关闭它。

安装时，模块会创建两个订单状态：Awaiting PayMongo payment 和 PayMongo payment on hold。在 Payment > Preferences 中，请确认模块已允许菲律宾比索、您顾客所在的国家以及他们的客户群组。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会在以下情况发出警告：商店的默认货币不是 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。

Cards (Visa, Mastercard):银行卡付款；3-D Secure 由 PayMongo 处理。
GCash, GrabPay, Maya, ShopeePay:电子钱包。
QR Ph:扫码付款。
BillEase, Atome:先买后付。
Direct online banking (BPI, UnionBank):从银行账户付款。

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_ 开头。

已保存的密钥和机密信息不会再次显示。该字段会保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved secrets：勾选某个密钥或机密信息，然后点击 Save 即可将其删除。空字段会保留已保存的值。

Webhook

即使顾客在付款后关闭了浏览器，webhook 也会告知您的商店付款已完成。请在 PayMongo Dashboard 中（或通过 PayMongo API）为测试和正式两种模式各创建一个 webhook，URL 使用本节 Webhook URL 中显示的地址。启用友好 URL 时，地址类似 https://your-shop/module/wcp_paymongo_payment_gateway/webhook，可能还会带有语言代码，例如 /en/。请完全按照设置中显示的内容复制 URL。

选择以下事件（本节也列出了它们）：

checkout_session.payment.paid：顾客已在 PayMongo 结账页面付款。
payment.paid：一笔付款已完成。
payment.failed：一次付款尝试失败。

将每个 webhook 的签名密钥（whsk_...）复制到 Test webhook secret 或 Live webhook secret 中。没有有效签名的 webhook 会被拒绝。签名使用其所属模式的密钥进行验证，并且事件的模式必须与之匹配，因此测试 webhook 绝不会确认正式付款。在创建或修改订单之前，每个事件都会使用该付款模式的私钥再次通过 PayMongo API 进行验证。PayMongo 会把整个账户的事件发送给每个 webhook；不是在本商店发起的付款事件会被忽略。没有 webhook 时，只有顾客付款后返回商店，订单才会被创建。

订单

Order status after payment：付款成功后设置的订单状态。

Payment accepted (Processing)：PrestaShop 为已付款订单设定的标准状态（默认）。
Delivered (Completed)：适用于无需配送的虚拟商品或可下载商品。

仍在处理中的付款会等待在 Awaiting PayMongo payment 状态。金额或货币不一致的情况，以及正式商店中的测试付款，总是会进入 PayMongo payment on hold。

高级

Debug log：将 PayMongo API 调用和 webhook 事件记录到模块文件夹中的 logs/paymongo_p_debug.log.php。该文件无法通过网页打开。即使开关关闭，错误和警告仍会始终被记录。密钥和顾客数据绝不会被记录。默认：关闭。

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

Delete data on uninstall：开启时，卸载模块会删除设置和日志。订单的 PayMongo ID、退款以及模块的订单状态始终会保留，因为退款和会计工作需要它们。默认：关闭。

结账

在支付步骤中，顾客选择付款方式（默认为 PayMongo (Card, GCash, GrabPay, Maya)）并看到其说明。在测试模式下，结账页面还会显示 Test mode: no real payment will be made. PayMongo 仅提供给总额至少为 ₱100.00 的 PHP 购物车。

确认后，模块会为购物车总额（以 PHP 计）创建一个 PayMongo Checkout Session，其中包含一行 Cart # 和购物车编号，并将顾客带到 PayMongo 结账页面。顾客的姓名、电子邮件、电话和账单地址会传递给 PayMongo。顾客在那里选择一种已选中的付款方式并付款。此时尚未创建订单。

付款后，顾客返回您的商店。只有在 PayMongo 确认付款后，订单才会被标记为已付款：当顾客返回以及 webhook 到达时，模块都会向 PayMongo API 查询付款情况。随后订单被创建，顾客会看到标准的订单确认页面，并显示 Your PayMongo payment has been received. 如果顾客返回时 PayMongo 仍在处理付款，订单会以 Awaiting PayMongo payment 状态创建，页面显示 PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. 如果该付款之后失败，页面会显示 Your PayMongo payment was not completed. Please contact us about this order. 如果顾客返回时无法连接 PayMongo，会出现 Payment confirmation 页面，提示顾客不要再次付款，并显示 Check again 按钮；webhook 一到达就会创建订单。

如果顾客在 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. 购物车会被保留。新的尝试会先检查之前的付款：如果它在此期间已被支付，则无需再次付款即可创建订单；否则之前的 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. 技术原因会写入日志。

即使商店处于维护模式，webhook 也能正常工作，并且不受商店国家限制的影响。

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

订单与退款

订单状态

No order yet：顾客已被带到 PayMongo 但尚未付款，或 PayMongo 尚未确认付款。此时只存在购物车。

Payment accepted or Delivered：付款已确认。状态依据 Order status after payment。付款会以 PayMongo 付款 ID（pay_...）作为交易 ID 记录，备注中会显示付款、金额、方式、模式以及确认方式（webhook 或返回）。

Awaiting PayMongo payment：顾客在 PayMongo 仍在处理付款时返回。当 PayMongo 确认后，订单会转为已付款状态。

PayMongo payment on hold：已付金额或货币与购物车总额不符（例如，付款开始后在另一个标签页中修改了购物车）；或者商店处于正式模式时，付款是在测试模式下完成的，因此未收到任何款项，也不记录付款；或者付款是在订单已取消之后到达的。备注会对此加以说明。请检查订单并进行处理，或者退还该笔付款。

Payment error：一个已签名的 payment.failed webhook 报告，处于 Awaiting PayMongo payment 状态的订单的最近一次付款尝试失败。备注会显示 PayMongo 的失败代码和信息。如果同一笔付款之后成功，订单会转为已付款状态。

Refunded：该付款已通过模块全额退款。

如果一个已付款的订单又收到第二笔付款（例如通过旧的结账链接），订单不会被更改。备注会提示您在 PayMongo Dashboard 中退还重复的付款。已付款后又被取消或退款的订单永远不会被重新打开。

PayMongo payment 区块

订单页面会显示一个 PayMongo payment 区块，其中包括 PayMongo 付款 ID 和方式、payment intent、checkout、模式、状态、已付金额和已退金额、测试付款的 Test mode 标识、订单的 PayMongo 备注以及退款历史。

退款

在 PayMongo payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via PayMongo。确认提示 Refund this amount through PayMongo? This cannot be undone. 支持全额和部分退款，最多保留两位小数。您需要具有编辑订单的权限；无需访问模块页面的权限。退款金额以 PayMongo 实际收取的金额为上限，因此在金额不一致后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款使用付款所属模式（测试或正式）的私钥发送，因此必须设置该模式的私钥。您输入的原因会作为退款备注发送给 PayMongo。如果 PayMongo 不接受退款，区块会显示错误，并且不会记录退款。成功的退款会添加到退款历史和备注中，包括 PayMongo 退款 ID 和状态。全额退款会将订单设为 Refunded。部分退款不会更改状态。

模块不会创建退款单据。订单页面上的 PrestaShop 标准退款按钮不会通过 PayMongo 退回款项。在 PayMongo Dashboard 中进行的退款不会同步到 PrestaShop。请改为从订单区块进行退款，或手动更新订单。

许可证密钥

模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayMongo Payment Gateway 位于 Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure 页面的最顶部，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店中移除密钥）。其下方是 Product: presta-payment-paymongo 一行和 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 账户中释放该名额。

如果没有有效的密钥，PayMongo 不会在结账时显示给顾客。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍然可以进行。

许可证到期后，模块会继续运行，但更新和支持需要续费。在您使用后台时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 PayMongo：请检查许可证是否有效，Enable/Disable 是否开启，当前模式是否设置了私钥（测试模式为 Test secret key，正式模式为 Live secret key），购物车是否为 PHP 货币，以及购物车总额是否至少为 ₱100.00。在 Payment > Preferences 中，请检查模块是否允许购物车货币、顾客所在国家以及顾客所属群组。

付款已成功，但没有创建订单：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_ 开头。

顾客在选择 PayMongo 时看到错误：请查看模块页面上的 Log 字段。错误的私钥会显示该付款方式暂时不可用的提示。未在您的 PayMongo 账户中启用的付款方式会导致 PayMongo 拒绝结账；请将其从 Payment methods 中移除。

正式商店中的测试付款：当商店处于正式模式时收到的测试付款，会使订单进入 PayMongo payment on hold 状态，并附带备注说明未收到任何款项。即使切换回测试模式，正式付款仍会始终被识别，并使用正式私钥退款。

付款后订单处于 PayMongo payment on hold：请阅读 PayMongo payment 区块中的备注（参见订单状态），然后处理订单或退还该笔付款。

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

开发人员可以通过 actionPaymongoPCheckoutSessionData 钩子修改 Checkout Session 数据。

卸载

进入 Modules > Module Manager，打开 VibeFox PayMongo Payment Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 PayMongo ID、退款以及订单状态 Awaiting PayMongo payment 和 PayMongo payment on hold 始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。

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