VibeFox PayMongo for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: Philippine peso (PHP). The payment method is hidden when the store currency, or the order currency on the Pay for order page, is not PHP.

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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_paymongo_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > PayMongo > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Paste your PayMongo secret keys, create the webhooks and paste their signing secrets (see Configuration).

6. Select the payment methods, turn on Enable/Disable and save. Test a payment with Test mode on, then untick it.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PayMongo. Above the fields the page warns you when the store currency 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), and shows Test mode is on: no real payments are made. while test mode is on. In the list of payment methods, PayMongo is marked as needing setup until the current mode has a secret key.

General

Enable/Disable: Enable PayMongo turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: PayMongo (Card, GCash, GrabPay, Maya).

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. 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. Untick it 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_.

Webhook

The webhook tells your store 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 this section of the settings. It looks like https://your-site/?wc-api=paymongo_p_webhook.

Select these events:

Copy the signing secret (whsk_...) of each webhook into Test webhook secret or Live webhook secret. Webhooks without a valid signature are rejected, and the mode of the event must match the mode of the signature. Every event is checked again through the PayMongo API before the order is changed. PayMongo sends the events of the whole account to every webhook; events of payments that were not created by this store are ignored. Without the webhook, payments are confirmed only when the customer returns to your store.

Orders

Order status after payment: the order status set after a successful payment. The status is set at once, without a second status change.

Advanced

Debug log: Log API calls and webhook events writes them to WooCommerce > Status > Logs, source wcp_paymongo_payment_gateway. Errors are always logged. Keys and customer data are never logged. Default: off.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. PayMongo IDs stored on orders are kept, because they are needed for refunds and accounting. Default: off.

Checkout

The customer chooses the payment method (by default PayMongo (Card, GCash, GrabPay, Maya)) and places the order. In test mode the checkout shows Test mode: no real payment will be made. The plugin creates a PayMongo Checkout Session for the order total in PHP, with one line Order # and the order 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.

The payment method is shown only for orders of at least ₱100.00. A smaller order total cannot be paid with PayMongo.

After paying, the customer returns to the order received page of your store. The order is marked paid only after PayMongo confirms it: the plugin asks the PayMongo API about the payment when the customer comes back and when the webhook arrives. If PayMongo is still processing the payment or cannot be reached, the customer still lands on the order received page, and the webhook completes the order later.

If the customer cancels on the PayMongo page or does not finish the payment, the customer comes to the Pay for order page with the message 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 order stays unpaid. A new attempt first checks the previous one: if it was paid in the meantime, the order is completed without a new payment; otherwise the previous PayMongo checkout link is expired, so the customer cannot pay 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 sees 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 added to the order notes.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

Pending payment: the customer was sent to PayMongo and has not paid yet, or PayMongo has not confirmed the payment yet. A note records each PayMongo checkout created for the order. While PayMongo is processing a payment, a note says so.

Processing or Completed: the payment was confirmed. The status follows Order status after payment. The order note shows the PayMongo payment, the amount, the method and the mode. The transaction ID is the PayMongo payment ID (pay_...). The order screen shows the PayMongo checkout, payment intent and mode under the billing address.

On hold: the paid amount or currency differs from the order (note amount/currency mismatch); or a payment was made in test mode while the store is in live mode, so no money was received; or the payment arrived after the order had been cancelled, for example by the stock hold timeout. The order note explains it. Check the order and process it or refund the payment.

Failed: a signed payment.failed webhook reported that the latest payment attempt of a pending order failed. The note shows the PayMongo failure code and message. The customer can pay again.

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. A cancelled or refunded order that had been paid is never reopened.

Refunds

Open the order, click Refund, enter the amount and click Refund via PayMongo (Card, GCash, GrabPay, Maya) (the button shows your payment method title). Full and partial refunds are supported. 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. If PayMongo does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the PayMongo refund ID and status.

Refunds made in the PayMongo Dashboard are not copied to WooCommerce. Refund from the WooCommerce order instead, or create a manual refund in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > PayMongo. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency is PHP and the order total is at least ₱100.00. Developers can change the minimum with the filter paymongo_p_minimum_amount.

The payment went through, but the order stays Pending payment: the webhook is not working and the customer did not come back to the store. In the PayMongo Dashboard check that a webhook exists in the mode you use, that its URL is exactly the one shown in the settings 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, or the order was being processed by another request at the same moment. PayMongo retries the webhook automatically.

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 placing the order: open the order notes or look at WooCommerce > Status > Logs, source wcp_paymongo_payment_gateway. 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 store: a test payment that arrives while the store is in live mode puts the order 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 On hold after payment: read the order note. The paid amount or currency differed from the order, the payment was a test payment, or it came after the order was cancelled. 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the temporary data and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and PayMongo IDs.

PayMongo is a trademark of its respective owner. This plugin is not affiliated with or endorsed by PayMongo.