VibeFox PayMongo for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Currency: Philippine peso (PHP). PayMongo is shown at checkout only for carts in PHP. If the default currency of your shop is not PHP, the settings page warns you, and customers must switch to PHP to see PayMongo.
PayMongo account: you need the secret API keys of your PayMongo account and a webhook for each mode (see Configuration). Only the secret keys (sk_test_..., sk_live_...) and the webhook signing secrets (whsk_...) are used. The public keys are not needed, because the payment page is hosted by PayMongo. The payment methods you offer must be activated for your PayMongo account.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox PayMongo Payment Gateway in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Paste your PayMongo secret keys, create the webhooks in PayMongo and paste their signing secrets (see Configuration).
5. Select the payment methods, turn on Enable/Disable and click Save. Test a payment with Test mode on, then turn it off.
On install the module creates two order statuses, Awaiting PayMongo payment and PayMongo payment on hold. In Payment > Preferences check that the module is allowed for the Philippine peso, the countries of your customers and their customer groups.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the default currency of the shop is not PHP, when the current mode has no secret key (PayMongo is then not shown at checkout) or no webhook secret (payments are then confirmed only when the customer returns to your shop), and shows Test mode is on: no real payments are made. while test mode is on.
PayMongo
Enable/Disable: Enable PayMongo turns the payment method on or off. Default: off.
Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: PayMongo (Card, GCash, GrabPay, Maya). Required.
Description: the text shown under the payment method at checkout. Default: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods: the methods offered on the PayMongo checkout page. Select only methods that are activated for your PayMongo account, otherwise PayMongo rejects the checkout. If none is selected, the defaults are used. Default: Cards, GCash, GrabPay and Maya.
API keys
Copy the secret keys from PayMongo Dashboard > Developers > API keys. Public keys are not needed. Each key must start with the expected prefix. A value with a wrong prefix is not saved: the page shows that the field must start with the prefix and that The previous value was kept.
Test mode: Enable test mode (no real payments). New payments use the test keys. Payments made earlier keep the mode they were made in, so status checks and refunds use the matching key. Default: on. Turn it off to take real payments.
Test secret key: the secret key of the test mode. It starts with sk_test_.
Test webhook secret: the signing secret of the test-mode webhook. It starts with whsk_.
Live secret key: the secret key of the live mode. It starts with sk_live_.
Live webhook secret: the signing secret of the live-mode webhook. It starts with whsk_.
Saved keys and secrets are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Clear saved secrets: tick a key or secret and click Save to remove it. An empty field keeps the saved value.
Webhook
The webhook tells your shop that a payment has been made, also when the customer closes the browser after paying. Create a webhook in the PayMongo Dashboard (or through the PayMongo API) for each mode, test and live, with the URL shown in Webhook URL in this section. With friendly URLs it looks like https://your-shop/module/wcp_paymongo_payment_gateway/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it.
Select these events (they are also listed in this section):
Copy the signing secret (whsk_...) of each webhook into Test webhook secret or Live webhook secret. Webhooks without a valid signature are rejected. The signature is checked with the secret of its own mode, and the mode of the event must match it, so a test webhook never confirms a live payment. Every event is checked again through the PayMongo API with the secret key of the payment's mode before an order is created or changed. PayMongo sends the events of the whole account to every webhook; events of payments that were not started in this shop are ignored. Without the webhook, an order is created only when the customer comes back to the shop after paying.
Orders
Order status after payment: the order status set after a successful payment.
Payments still being processed wait in Awaiting PayMongo payment. Amount or currency mismatches and test payments on a live shop always go to PayMongo payment on hold.
Advanced
Debug log: logs PayMongo API calls and webhook events to logs/paymongo_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, also while the switch is off. Keys and customer data are never logged. Default: off.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Delete data on uninstall: when on, uninstalling the module deletes the settings and the log. The PayMongo IDs stored for orders, the refunds and the module's order statuses are always kept, because they are needed for refunds and accounting. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default PayMongo (Card, GCash, GrabPay, Maya)) and sees its description. In test mode the checkout also shows Test mode: no real payment will be made. PayMongo is offered only for carts in PHP with a total of at least ₱100.00.
After confirming, the module creates a PayMongo Checkout Session for the cart total in PHP, with one line Cart # and the cart number, and sends the customer to the PayMongo checkout page. The customer's name, e-mail, phone and billing address are passed to PayMongo. There the customer chooses one of the selected methods and pays. No order exists yet at this point.
After paying, the customer returns to your shop. The order is marked paid only after PayMongo confirms it: the module asks the PayMongo API about the payment when the customer comes back and when the webhook arrives. The order is then created and the customer sees the standard order confirmation page with Your PayMongo payment has been received. If PayMongo is still processing the payment when the customer comes back, the order is created in Awaiting PayMongo payment and the page shows PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. If that payment later fails, the page shows Your PayMongo payment was not completed. Please contact us about this order. If PayMongo cannot be reached when the customer comes back, a Payment confirmation page asks the customer not to pay again and shows a Check again button; the webhook creates the order as soon as it arrives.
If the customer cancels on the PayMongo page or does not finish the payment, the customer is back at checkout with You cancelled the PayMongo payment. You can try again or choose another payment method. or Your PayMongo payment was not completed. You can try again or choose another payment method. The cart is kept. A new attempt first checks the previous one: if it was paid in the meantime, the order is created without a new payment; otherwise the previous PayMongo checkout link is expired, so the cart cannot be paid twice. While the previous payment is still being processed, the customer sees Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.
If PayMongo cannot start the payment, the customer stays at checkout with a short message, for example The payment could not be started. Please try again or choose another payment method. or PayMongo could not be reached. Please try again in a moment. The technical reason is written to the log.
The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.
The module takes one-time payments on the PayMongo page. It has no card fields on your own checkout page, no saved cards, no subscriptions or recurring payments, no installments and no separate authorize and capture.
Orders and refunds
Order statuses
No order yet: the customer was sent to PayMongo and has not paid, or PayMongo has not confirmed the payment yet. Only the cart exists.
Payment accepted or Delivered: the payment was confirmed. The status follows Order status after payment. The payment is recorded with the PayMongo payment ID (pay_...) as the transaction ID, and a note shows the payment, the amount, the method, the mode and how it was confirmed (webhook or return).
Awaiting PayMongo payment: the customer came back while PayMongo was still processing the payment. The order moves to the paid status when PayMongo confirms it.
PayMongo payment on hold: the paid amount or currency differs from the cart total (for example, the cart was changed in another tab after the payment started); or a payment was made in test mode while the shop is in live mode, so no money was received and no payment is recorded; or the payment arrived after the order had been cancelled. The note explains it. Check the order and process it or refund the payment.
Payment error: a signed payment.failed webhook reported that the latest payment attempt of an order in Awaiting PayMongo payment failed. The note shows the PayMongo failure code and message. If the same payment succeeds later, the order moves to the paid status.
Refunded: the payment was fully refunded through the module.
If a second payment arrives for an order that is already paid, for example on an old checkout link, the order is not changed. A note asks you to refund the duplicate payment in the PayMongo Dashboard. An order that was paid and then cancelled or refunded is never reopened.
PayMongo payment block
The order page shows a PayMongo payment block with the PayMongo payment ID and method, the payment intent, the checkout, the mode, the status, the amount paid and the amount refunded, a Test mode badge for test payments, the PayMongo notes of the order and the refund history.
Refunds
In the PayMongo payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via PayMongo. Confirm the question Refund this amount through PayMongo? This cannot be undone. Full and partial refunds are supported, with at most two decimals. You need the right to edit orders; access to the Modules pages is not needed. Refunds are limited to the amount PayMongo actually charged, so after an amount mismatch you can refund up to what the customer paid, not the order total. The refund is sent with the secret key of the mode the payment was made in (test or live), so that mode's key must be set. The reason you enter is sent to PayMongo as the refund note. If PayMongo does not accept the refund, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the PayMongo refund ID and status. A full refund sets the order to Refunded. A partial refund does not change the status.
The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through PayMongo. Refunds made in the PayMongo Dashboard are not copied to PrestaShop. Refund from the order block instead, or update the order manually.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayMongo Payment Gateway is the first block on Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-paymongo and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, PayMongo is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.
Troubleshooting
PayMongo does not appear at checkout: check that the license is active, Enable/Disable is on, the current mode has a secret key (Test secret key in test mode, Live secret key in live mode), the cart is in PHP and the cart total is at least ₱100.00. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.
The payment went through, but no order was created: the webhook is not working and the customer did not come back to the shop. In the PayMongo Dashboard check that a webhook exists in the mode you use, that its URL is exactly the one shown in Webhook URL and that the three events are selected. Check that its signing secret is in the matching field (Test webhook secret or Live webhook secret).
Webhook answers Invalid signature: the signing secret of that mode is missing or belongs to another webhook. Paste the signing secret of the webhook into the field of its mode.
Webhook answers Mode mismatch: a test event was signed as live or the other way round. Check that each webhook belongs to the right mode.
Webhook answers Temporary error: the payment could not be checked through the PayMongo API, for example because the secret key of the payment's mode is missing. PayMongo retries the webhook automatically.
Webhook answers Busy, retry: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). PayMongo retries the webhook automatically. The reason is in the Log.
Webhook answers Ignored: the event belongs to a payment that was not started in this shop, or to another mode. Nothing is changed.
The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from PayMongo.
The value was not saved: a key was pasted into the wrong field. Secret keys start with sk_test_ or sk_live_, webhook secrets with whsk_.
The customer sees an error when choosing PayMongo: look at the Log field on the module page. A wrong secret key gives the message that the payment method is temporarily unavailable. A payment method that is not activated for your PayMongo account makes PayMongo reject the checkout; remove it from Payment methods.
Test payments on a live shop: a test payment that arrives while the shop is in live mode puts the order in PayMongo payment on hold with a note that no money was received. Live payments are always recognised, also after switching back to test mode, and are refunded with the live key.
Order is PayMongo payment on hold after payment: read the notes in the PayMongo payment block (see Order statuses), then process the order or refund the payment.
Refund fails with a message about the mode: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.
Developers can change the Checkout Session data with the hook actionPaymongoPCheckoutSessionData.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox PayMongo Payment Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the log are deleted. If it is off, all settings are kept for a later re-install. The PayMongo IDs of orders, the refunds and the order statuses Awaiting PayMongo payment and PayMongo payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.
PayMongo is a trademark of its respective owner. This module is not affiliated with or endorsed by PayMongo.