VibeFox Comgate 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 and json extensions.

HTTPS: your store must be reachable over HTTPS from the internet, without a firewall or basic authentication in front of it, so that Comgate can deliver the background notification.

Currency: the order currency must be CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK or SEK. For other currencies and for totals below the Comgate minimum the payment method is hidden at checkout. HUF payments are rounded to whole forints, as Comgate requires.

Comgate account: you need the Merchant ID and the secret (password for background communication) of your shop connection in the Comgate client portal, and the notification URL set there (see Configuration). Comgate uses the same Merchant ID and secret for test and live payments.

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-comgate-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/ComgatePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_ComgatePayment 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 Comgate 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. Enter the Merchant ID and Secret from the Comgate client portal and set the notification URL there (see Configuration). Keep Test mode at Yes, set Enable to Yes, click Save Config and place a test order. When everything works, set Test mode to No and click Save Config.

The module adds the Comgate payment method to the Magento checkout. 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 its own tables for the Comgate payment attempts and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Comgate Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts are entered with a point, for example "9.99".

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 (Enter a title for the payment method (1 to 128 characters).); a Sort order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater, a comma included (Order total must be a number, 0 or greater.). The Merchant ID and the secret are saved as entered, only spaces at the start and end are removed; they are not checked with Comgate when you save.

General

Enable: shows or hides Comgate at checkout. It is shown only when the Merchant ID and the Secret are both filled in. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Comgate. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely via Comgate — cards, bank transfers, wallets and more.

Sort order: the position among the payment methods at checkout. A whole number. Default: 0.

Connection

Take the shop identifier (Merchant ID) and the password (secret) from the Comgate client portal, in the settings of your shop connection. In the same place set the URL for passing the payment result (background notification) to the notification URL shown in the Comgate portal URLs row of this group (see Notification URL below).

Merchant ID: the Comgate e-shop identifier (merchant).

Secret: the password for background communication (secret) of this shop connection. Magento stores it encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved secret, type a new value to change it. As the hint under the field says, Clear the field to remove the saved secret; asterisks keep it.

Test mode: creates test payments (no money is charged). Comgate uses the same Merchant ID and secret for test and live payments; test payments are marked with test=true. While it is on, customers see TEST MODE: no real money is charged. under the payment method. Refunds are always sent in the mode of the original payment. Default: Yes. Set it to No to take real payments.

Page

Payment Methods: which Comgate payment methods the customer can choose from. Only methods enabled for your shop in Comgate are shown.

Language: the language of the Comgate payment page. Automatic (default) uses the locale of the store view where the order was placed when Comgate supports it, otherwise English. You can also choose one of 26 languages.

Orders

Order Status After Payment: the order state set when Comgate confirms the payment.

Payments that do not match the order, test payments while the store is live and pre-authorized payments always put the order On Hold.

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

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

Minimum Order Total: offer Comgate only from this order total, in the base currency of your store. 0 or empty means no minimum. The Comgate minimum of the currency (for example 1 CZK, 0.10 EUR or 100 HUF) always applies.

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

Advanced

Debug log: writes API requests, notifications and confirmations to var/log/comgate_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. The secret, e-mail addresses and return tokens are hidden in the log. Errors are always logged. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes and the log (see Uninstall). The license key is always removed. Orders, invoices, credit memos and the Comgate payment and refund records are always kept. Default: No.

Notification URL

After the Advanced section the Comgate portal URLs row shows two addresses. The first is the notification URL. It looks like https://your-store/wcpcomgategateway/webhook/index. Copy the URL exactly as the settings show it and enter it in the Comgate portal as the URL for passing the payment result. Comgate calls it after every payment; the module then re-checks the payment with the Comgate status API before it changes anything. The notification is checked with the Merchant ID and secret of the default store view, so enter them in the Default Config or for the website of the default store view.

Return URLs for the customer are sent with every payment. If the portal asks for return URLs (paid, cancelled, pending) too, use the second address of the row, which ends with wcpcomgategateway/checkout/back?id=${id}&refId=${refId}.

While Enable is Yes, the row also shows warnings: Comgate: Merchant ID / secret are missing. The payment method is hidden at checkout.; Comgate: the store currency … is not supported. The method is hidden for unsupported checkout currencies.; and Comgate test mode is on. No real money is charged. while test mode is on.

The last row, Debug log, shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Comgate) and sees the description and the note You will be redirected to Comgate to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates the payment at Comgate for the order total in the order currency and redirects the customer to the Comgate payment page. The customer's e-mail, name and billing country are passed to Comgate, and the payment is labelled Order and the order number. On the Comgate page the customer pays with one of the methods you allowed. Card data never touches your site.

After paying, the customer returns to your store. The order is marked paid only after Comgate confirms it: the module reads the payment from the Comgate status API, both when the background notification arrives and when the customer comes back, and checks that the transaction, the order, the amount and the currency match. The notification and the return are handled even when Enable is No or the license is not active.

After a confirmed payment Magento creates the invoice with the Comgate transaction ID as the transaction ID, the order moves to the state set in Order Status After Payment and the order e-mail is sent. The customer sees the standard order success page. If the order was put on hold, the page adds Your payment is being reviewed by the store. A customer who comes back in another browser lands on the home page.

If the payment is not confirmed yet when the customer comes back, for example a bank transfer on its way, or Comgate cannot be reached at that moment, a plain page shows Comgate has not confirmed your payment yet. Please do not pay again. with a Check again link. The notification confirms the order as soon as Comgate confirms the payment.

If the payment is cancelled or expires, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your payment was cancelled or expired. Please try again. The customer can pay again or choose another payment method. Before a new Comgate payment of the same cart is started, the earlier attempt is checked at Comgate first: a cart that is already paid is not charged again, and an attempt that is still open is cancelled at Comgate. A return link that does not match the payment shows We could not verify the Comgate payment. in the cart.

If Comgate cannot start the payment, the order is cancelled, the cart is restored and the customer sees We could not start the Comgate payment. Please try again or choose another payment method. in the cart. The technical reason is written to the log.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). When a Comgate order is cancelled in Magento, by this cron or in the Admin, the module cancels its open payment at Comgate too. If Comgate still reports a payment for a cancelled order, the order is not invoiced and not reopened: a note asks you to review the payment.

The module works with the standard Magento checkout. It takes one-time payments on the Comgate page only. It has no recurring payments, subscriptions or saved cards, no embedded Comgate checkout, no Apple Pay or Google Pay buttons on your site (they are available on the Comgate page) and no capture or cancellation of pre-authorizations from Magento. Comgate is not offered for orders created in the Admin or for checkout with multiple addresses. Without the notification the payment status is not polled automatically; it is checked only when the customer returns.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Comgate, but Comgate has not confirmed the payment yet. There is no invoice.

Processing or Complete: Comgate reported the payment as PAID with the same amount and currency. The state follows Order Status After Payment. The invoice is created with the Comgate transaction ID, and a note shows how the payment was confirmed (notification or return) and the transaction ID. Test payments get the note Test payment — no money was charged.

On Hold: the paid amount or currency differs from the order (the note shows the received amount), a test payment was confirmed while the store is in live mode (no money was received), or the payment is only authorized (pre-authorization on your Comgate account). No invoice is created. Before the hold the order is moved from Pending Payment to Processing, so Unhold returns it to Processing and the Pending Payment cron does not cancel it. An authorized payment is invoiced automatically when you capture it in the Comgate portal and Comgate reports it as PAID, whether the order is still On Hold or already unheld; if it is cancelled or expires there, the order is cancelled.

Canceled: the payment was cancelled or expired at Comgate, the payment could not be started, or the order was cancelled in Magento.

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

A paid or refunded order is never changed by a later notification, and repeated notifications and returns, even at the same moment, never invoice an order twice. If Comgate reports another payment for an order or a cart that is already paid, nothing is invoiced: a note asks you to refund the duplicate in the Comgate portal. The notes are order comments that the customer does not see.

Comgate payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Comgate transaction, Comgate status, Comgate amount and Comgate mode (test or live). It is shown also when the module is disabled. The customer sees only the payment method title.

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 Comgate. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Comgate.

The refund is made in the order currency, up to the amount Comgate charged minus the amounts already refunded through the module. HUF refunds must be whole forints. Before the refund the module checks the payment at Comgate: only PAID payments can be refunded. The refund is sent in the mode (test or live) of the original payment. If Comgate does not accept the refund, Magento shows the error and the credit memo is not created. A full refund closes the order. Refunds are available once Comgate has confirmed the payment and the order has an invoice; an order on hold has no invoice, so refund it in the Comgate portal.

Refunds made in the Comgate portal are not reported back to the store. Create a credit memo with Refund Offline to record them.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Comgate Gateway is the first row of the VibeFox Comgate Gateway group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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-comgate 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, Comgate is not shown to customers at checkout. If a payment is started anyway, no Comgate payment is created: the order is cancelled, the cart is restored and the customer sees We could not start the Comgate payment. Please try again or choose another payment method. 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

Comgate does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that Merchant ID and Secret are filled in. The Comgate portal URLs row shows a warning when one is missing. Check that the cart currency is supported and the order total is not below the Comgate minimum (for example 1 CZK, 0.10 EUR or 100 HUF). 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: Comgate has not delivered the background notification. Check the URL for passing the payment result in the Comgate portal (exactly the notification URL of the Comgate portal URLs row), that your store is reachable over HTTPS from the internet, that the Merchant ID and secret are set for the default store view, and the log (turn on Debug log). Comgate repeats undelivered notifications; the module answers with an error whenever it did not process one, so it will be retried. The order is also confirmed when the customer returns to the store.

Notification answers Invalid merchant or secret: the Merchant ID or secret of the default store view does not match the shop connection in the Comgate portal.

Notification answers Gateway not configured: the Merchant ID or secret is empty. Comgate retries once they are filled in.

Notification answers Unknown transaction, Order not found or Reference mismatch: the notification belongs to a payment that was not created by this store for that order. Nothing is changed.

Notification answers Status verification failed, Status verification rejected or Busy, retry later: the Comgate status API could not be reached, rejected the request, or the order was being processed by another request at the same moment. Busy is also the answer when the order could not be updated; the reason is in the log. Comgate retries the notification.

The notification URL shows code=1&message=POST%20required in the browser: this is normal. The URL accepts only requests from Comgate.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next notification or return that reaches the store.

The customer sees We could not verify the Comgate payment: the return link did not match the payment, for example it was edited. If money was charged, the notification still confirms the order. Check the payment in the Comgate portal before the customer pays again.

The customer is back in the cart with We could not start the Comgate payment: turn on Debug log and look at the Debug log row. A wrong Merchant ID or secret, a payment method not enabled for your shop in Comgate or an inactive license are the usual causes. The order of that attempt is cancelled.

The order is On Hold: read the notes on the order. The paid amount or currency differed, a test payment arrived in live mode, or the payment is only authorized. Check the payment in the Comgate portal and complete the order or refund the payment there. After Unhold the order is Processing without an invoice: Magento does not cancel it automatically, so cancel it yourself if you refunded or cancelled the payment.

Refund fails: read the message Magento shows. Comgate rejected the refund: the amount exceeds the refundable amount. or Invalid refund amount: at most … can be refunded. means the amount is higher than what is left to refund. Comgate payment cannot be refunded in its current status. means the payment is not PAID at Comgate. Comgate refunds in HUF must be whole forints. means the credit memo total has decimals.

The refund says Comgate could not be reached. Check the refund outcome in the Comgate portal before retrying.: the answer of Comgate was lost, and the credit memo was not created. The refund may still have been made: check it in the Comgate portal first. If it was made, record it with Refund Offline instead of trying 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) cannot be refunded online; refund it in the Comgate portal.

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.

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_ComgatePayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_ComgatePayment to remove the data, then bin/magento module:disable Vibefox_ComgatePayment, delete the folder app/code/Vibefox/ComgatePayment 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 of all scopes and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Comgate payment attempts 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.

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