VibeFox PayMongo for Adobe Commerce — 도움말

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

Currency: Philippine peso (PHP). PayMongo is shown at checkout only when the customer pays in PHP and the order total is at least ₱100.00. If the base currency or the default display currency of the store is not PHP, the settings page warns you.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-paymongo-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PaymongoPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PaymongoPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox PayMongo Payment Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Paste your PayMongo secret keys, create the webhooks in PayMongo and paste their signing secrets (see Configuration). Select the payment methods, set Enable to Yes and click Save Config. Test a payment with Test mode set to Yes, then set it to No.

The module adds the PayMongo (Card, GCash, GrabPay, Maya) payment method to the Magento checkout (the name is the Title setting). It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the PayMongo payment attempts, webhook events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayMongo Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. The license block is shown in the Default Config. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Title is required and must not exceed 128 characters.); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a non-negative number.). Use a dot as the decimal separator, for example 9.99.

When Enable is Yes, the Webhook row shows warnings for the selected scope: The store currency … is unsupported: PayMongo accepts PHP, minimum ₱100., Enter the secret API key for the current mode. (PayMongo is then not shown at checkout), Enter the webhook secret. Without it, payments are confirmed only when the customer returns. and, while test mode is on, Test mode is on: no real payments are made.

The fields are in one list. They are described below in groups.

General

Enable: shows or hides PayMongo at checkout. It is shown only when the secret key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: PayMongo (Card, GCash, GrabPay, Maya). Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it 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. An empty selection restores Card, GCash, GrabPay and Maya, which are also the default.

Sort Order: the position among the payment methods at checkout. A whole number.

API keys

Copy the secret keys from PayMongo Dashboard > Developers > API keys. Public keys are not needed.

Test mode: new payments use the test keys. No real money is charged. Default: Yes. Set it to No to take real payments. While it is on, customers see Test mode: no real payment will be made. under the payment method. Payments made earlier keep the mode they were made in, so status checks and refunds use the matching key.

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

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key or secret, clear the field and click Save Config. A new value with a wrong prefix is not saved: the previous value is kept, the other fields are saved, and a warning is shown, for example Invalid prefix for test_secret_key — the previous value was kept.

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 the Webhook row. The URL is the storefront address of the store view of the selected scope (in the Default Config, the default store view) and looks like https://your-store/wcppaymongopaymentgateway/checkout/webhook/?___store=default. Copy the URL exactly as the settings show it.

Select these events (they are also listed in the Webhook row):

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 changed.

A webhook URL serves the payments of its own store view. If your store has several store views that take PayMongo payments, switch the Scope to each store view, copy its URL and create a webhook for it in each mode. PayMongo sends the events of the whole account to every webhook; events of payments that were not started in that store view are ignored. Without the webhook, an order is confirmed only when the customer comes back to the store after paying.

Orders

Order status after payment: the order status set after a successful payment.

Payments still being processed by PayMongo wait in Pending Payment. Amount or currency mismatches and test payments on a live store always go to On Hold.

Conditions

Payment from Applicable Countries: All Allowed Countries offers PayMongo for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer PayMongo only for billing addresses in these countries.

Minimum Order Total: offer PayMongo only from this order total, in the base currency of your store. Empty or 0 means no minimum. The PayMongo minimum of ₱100.00 always applies.

Maximum Order Total: offer PayMongo only up to this order total, in the base currency. Empty or 0 means no maximum.

Advanced

Debug log: logs PayMongo API calls and webhook events to var/log/paymongo_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged, also while the switch is off. Keys and customer data are never logged. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes only the module settings, its cache and the log (see Uninstall). The license key is always removed. Payment attempts, refunds, webhook events and order history are always kept. Default: No.

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 when the customer pays in PHP and the order total is at least ₱100.00.

After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a PayMongo Checkout Session for the order total in PHP, with one line Order # and the order number and the list of ordered items, and sends the customer to the PayMongo checkout page. The PayMongo page shows the description Order # and the order number from your store name: the Store Name in Stores > Configuration > General > General > Store Information of the store view, or the name of its store when that field is empty. The customer's name, e-mail, phone and billing address are passed to PayMongo. PayMongo does not send its own e-mail receipt. There the customer chooses one of the selected methods and pays.

After paying, the customer returns to your store. 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. Magento then creates the invoice with the PayMongo payment ID, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page with PayMongo payment confirmed. A customer who comes back in another browser lands on the home page with the same message. If PayMongo is still processing the payment or cannot be reached, the customer sees a short page Your PayMongo payment is being confirmed. Do not pay again. with a Check again link; the webhook confirms the order as soon as it arrives.

If the customer cancels on the PayMongo page, the PayMongo checkout is expired, the order is cancelled (the stock goes back) and the customer is back in the cart with Your PayMongo payment was not completed. The cart is restored. A signed payment.failed webhook for the latest attempt of an order in Pending Payment also cancels the order. A new attempt for the same cart first checks the previous one: if it is not paid, its PayMongo checkout link is expired, so the cart cannot be paid twice. If the previous payment is still being processed or needs review, the customer sees The existing PayMongo payment is being confirmed or requires review. Do not pay again.; if the cart has already been paid, This cart already has a payment. Please check the existing order.

If PayMongo rejects the start of the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example PayMongo could not start payment. Please check your order before retrying. The technical reason is written to the log. If the answer of PayMongo is unknown (for example, a timeout), the order is not cancelled and stays in Pending Payment, because a PayMongo checkout may already exist; a later attempt for that cart shows A previous checkout request needs verification. Do not pay again; contact the store.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the module first asks PayMongo about the payment and expires its open checkout. If the payment is paid or still being processed, PayMongo cannot be reached, the secret key of the payment's mode is not set or the checkout does not expire, the order is not cancelled. In the Admin, Magento shows PayMongo payment must be verified before cancelling this order. The cron leaves the order in Pending Payment, adds a note with the reason, such as PayMongo payment must be verified before this order is cancelled: PayMongo reports the payment as processing or succeeded., and goes on with the other expired orders. The cron tries again on later runs and cancels the order once the checkout is verified and expired.

The module works with the standard Magento checkout. It 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. PayMongo is not offered for orders created in the Admin or for multiple-address checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to PayMongo, but PayMongo has not confirmed the payment yet, or the payment is still being processed (a note says PayMongo payment is processing. Awaiting final confirmation.). There is no invoice.

Processing or Complete: the payment was confirmed. The status follows Order status after payment. The invoice is created with the PayMongo payment ID (pay_...) as the transaction ID, and a note shows the payment, the amount, the method and how it was confirmed (webhook or return).

On Hold after a review reason: the paid amount or currency differs from the order total; or a test payment arrived while the store is in live mode, so no money was received; or the payment arrived for an order that was cancelled, closed or on manual hold. No invoice is created and the order is not reopened. An order still in Pending Payment is first moved to Processing and then put on hold, so Unhold returns it to Processing and the Pending Payment cron does not cancel it while the money is at PayMongo. The note shows the payment, the amount and the reason. Check the order and fulfil it, or refund the payment from the PayMongo block (see below).

Canceled: the customer cancelled or did not complete the payment, PayMongo rejected the start of the payment, a payment.failed webhook reported that the latest attempt failed (the note shows the PayMongo failure code and message), or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for an order that is already paid, or another order of the same cart has already been paid, the order is not changed and no second invoice is created. A note asks you to reconcile or refund the duplicate payment. The notes are order comments that the customer does not see.

PayMongo payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and PayMongo intent, PayMongo payment, Payment mode and Payment method. The customer sees only the payment method title. Below, on the Information tab, the block VibeFox PayMongo Payment Gateway lists every payment attempt of the order: Attempt, Session, Intent, Mode, Status, Payment, Requested amount, Reported amount, Payment method, and the refunds with their PayMongo refund ID, amount, status and credit memo. The block is also shown when Enable is No.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through PayMongo. Full and partial refunds are supported, with at most two decimals. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through PayMongo.

The refund is made in PHP, up to the amount PayMongo actually charged minus the amounts already refunded. It 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, Magento shows the error, for example PayMongo rejected the refund. No native credit memo was saved. or Invalid refund amount: at most … can be refunded., and the credit memo is not created. After a successful refund Magento records it with the PayMongo refund ID (ref_...) as the transaction ID. A full refund closes the order.

If the result of a refund is unknown (for example, a timeout), Magento shows The refund result is uncertain. Check PayMongo before retrying. No refund for that payment is sent again automatically; further refunds show An earlier refund has an uncertain result. Reconcile it in PayMongo before sending another request. If PayMongo accepted a refund but Magento could not save the credit memo, create the credit memo again with the same amount: the accepted refund is used and no second refund is sent.

Refund held or duplicate payments: a payment that was put on hold or reported as a duplicate has no invoice. Admin users who may create credit memos can refund it in the VibeFox PayMongo Payment Gateway block: enter Refund amount (PHP) and optional Notes and click Refund held payment. The refund is limited to the amount PayMongo charged. A note with the refund ID is added to the order; no invoice or credit memo is created.

Refunds made in the PayMongo Dashboard are not copied to Magento. Create a credit memo with Refund Offline or update the order manually. A payment confirmed without a PayMongo payment ID (pay_...) cannot be refunded online; refund it in the PayMongo Dashboard.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayMongo Payment Gateway is the first row of the VibeFox PayMongo Payment Gateway group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-paymongo and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

PayMongo does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a secret key: Test secret key in test mode, Live secret key in live mode. The Webhook row shows a warning when the key is missing. The customer must pay in PHP and the order total must be at least ₱100.00. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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 Webhook row for the store view of the order and that the three events are selected. Check that its signing secret is in the matching field (Test webhook secret or Live webhook secret) for that store view. The order is also confirmed when the customer returns to the store after paying.

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 with HTTP 503: the order was being confirmed by another request at the same moment. PayMongo retries the webhook automatically.

Webhook answers Ignored: the event belongs to a payment that was not started in this store view, 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.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. PayMongo retries the webhook later, and the order is also confirmed when the customer returns.

The value was not saved: a key was pasted into the wrong field (Invalid prefix for … — the previous value was kept.). Secret keys start with sk_test_ or sk_live_, webhook secrets with whsk_.

The customer is back in the cart with an error after Place Order: turn on Debug log and look at the Log field. A wrong secret key or a payment method that is not activated for your PayMongo account makes PayMongo reject the checkout; fix the key or remove the method from Payment methods. The order of that attempt is cancelled.

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 invoice was created. 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 notes and the VibeFox PayMongo Payment Gateway block (see Order statuses), then fulfil 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 (The secret key for this payment mode is missing.). Enter it and try again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) is refunded with Refund held payment in the PayMongo block.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Developers can change the Checkout Session data with the Magento event paymongo_p_checkout_session_data. The amount, reference, metadata and return URLs always stay as the module sets them.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PaymongoPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PaymongoPayment to remove the data, then bin/magento module:disable Vibefox_PaymongoPayment, delete the folder app/code/Vibefox/PaymongoPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The PayMongo payment attempts, webhook events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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