VibeFox Mollie 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.
Order currency: the currency of the order (the currency the customer sees at checkout) must be one of the currencies supported by Mollie: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. For other currencies the payment method is hidden at checkout. Which payment methods Mollie offers depends on the currency and your account.
Internet access to your store: Mollie sends webhooks to your store, so the site must be reachable from the internet. Without webhooks, orders are still confirmed when the customer returns from Mollie.
Mollie account: you need the API keys from Mollie Dashboard > Developers > API keys. Test keys start with test_, live keys with live_. No other keys or secrets are needed. The payment methods themselves are enabled in your Mollie 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-mollie-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/MolliePayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_MolliePayment 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 Mollie 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 your test and live API keys (see Configuration). No webhook has to be configured in Mollie. Set Enable to Yes and click Save Config. Leave Test Mode on Yes until you have made a test payment, then set it to No.
The module adds the Mollie 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 two tables for the Mollie payment attempts and refunds.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Mollie Gateway, in the standard Magento configuration form. The fields are one list on the page; below they are grouped by topic. 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. Set Remove data on uninstall in the Default Config. Save Config saves the whole page. Amounts accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title (Enter a title for the payment method.), 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 (Enter a non-negative order total.).
After Save Config, while Enable is Yes, the page warns you with Enter the API key of the selected Mollie mode. The method is hidden without it. when the API key of the current mode is empty, and with The current currency is not supported by Mollie. In both cases the payment method is hidden at checkout.
General
Enable: shows or hides Mollie at checkout. It is shown only when the API 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: Mollie. Required.
Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely via Mollie.
Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.
API keys
Find your API keys in the Mollie Dashboard under Developers > API keys. Test and live keys are separate.
Test Mode: uses the test API key for new payments. No real payments are processed. On the Mollie test checkout page you can choose the result of the payment. While it is on, customers see TEST MODE — Mollie test environment, no real money is charged. under the payment method. Payments made in the other mode keep using the key of their own mode for status checks and refunds. Default: Yes.
Test Api Key: your Mollie test API key (starts with test_).
Live Api Key: your Mollie live API key (starts with live_).
Magento stores the keys encrypted and shows only a mask (******) after saving. As the comment under each key says, Leave blank to retain the saved key. Wrong key format keeps the previous value. Leave the field as it is or empty to keep the saved key, type a new value to change it. A key that does not start with test_ or live_ followed by at least 30 letters and digits is not saved: the previous key is kept, the other settings are saved, and the page shows Invalid Mollie API key. Its saved value was kept; other settings were saved.
Clear saved test api key and Clear saved live api key: set to Yes and click Save Config to delete the saved key. The field goes back to No after saving.
Setup and webhook
This field shows the webhook URL. No webhook setup is needed: the module sends the webhook URL to Mollie with every payment. The field shows the storefront address of the default store view, for example https://your-store/wcpmolliegateway/webhook/index/; a payment started in another store view uses the address of that store view. The URL must be reachable from the internet, otherwise orders are confirmed only when the customer returns from Mollie. The field also reminds you that notifications carry only a payment ID, that the payment is always checked with the Mollie API, and that authorized payments must be captured in the Mollie Dashboard.
Orders
Order Status After Payment: the order status set after a successful payment.
Bank transfers wait in Pending Payment. Authorized payments and amount or currency mismatches go to On Hold.
Conditions
Payment from Applicable Countries: All Allowed Countries offers Mollie for every country your store allows, Specific Countries only for the countries below.
Payment from Specific Countries: offer Mollie only for billing addresses in these countries.
Minimum Order Total: offer Mollie only from this order total, in the base currency of your store. Empty or 0 means no minimum.
Maximum Order Total: offer Mollie only up to this order total, in the base currency. Empty or 0 means no maximum.
Advanced
Debug log: writes API calls and webhooks to var/log/molg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this is off. API keys and customer contact data are not 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 the gateway settings and the log (see Uninstall). The license key is always removed. As the comment says, Order, transaction and refund history is always retained. Default: No.
Checkout
At the payment step the customer chooses the payment method (by default Mollie) and sees the description. 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 Mollie payment for the order total in the order currency (JPY and ISK without decimals), with the description Order # and the order number, and sends the customer to the Mollie hosted checkout. There the customer chooses one of the payment methods enabled in your Mollie account and pays.
Mollie webhooks carry no signature, only the payment ID. So the module never trusts a webhook as such: it accepts only payment IDs it created itself, reads the payment from the Mollie API with the key of the mode the payment was made in, checks that the payment belongs to the cart and compares the paid amount and currency with the order. The order is marked paid only after Mollie confirms it this way. Magento then creates the invoice with the Mollie payment ID, sets the status from Order Status After Payment and sends the order e-mail. The module handles these Mollie payment statuses:
When the customer comes back, the module checks the payment with the Mollie API the same way. A paid payment leads to the standard order success page. If the order is on hold, the success page shows Your Mollie payment is being reviewed by the shop. Do not pay again. If the payment was cancelled, failed or expired, the order is cancelled, the cart is restored and the customer is back in the cart with The payment was cancelled, expired or failed. You can try again or choose another payment method. If Mollie has not confirmed the payment yet, for example for a bank transfer or when Mollie cannot be reached, a Payment confirmation page says We could not confirm your payment yet. If you completed it, your order will be updated automatically. Please do not pay again. with the buttons Check again and Back to checkout; the webhook confirms the order as soon as it arrives. A customer who comes back in another browser lands on the home page with Your payment status was checked. Sign in or contact the shop to view your order.
When the customer pays again for the same order, the still-open Mollie payment of the same amount is reused instead of creating a second payable one. When the cart is paid with a new order, an older open payment of the same cart is cancelled at Mollie first; if Mollie does not allow that, the customer sees An earlier payment is still open. Do not pay again. If an earlier payment of the cart turns out to be paid, it is processed instead of a new payment. If the cart already has a paid order, the customer sees This cart already has a paid order. Do not pay again.
If Mollie cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Mollie refused the payment request. Choose another payment method. (a wrong API key, or an amount or currency Mollie does not accept) or Mollie is not available for this order. The technical reason is written to the log. If Mollie gave no clear answer, the order is kept and the customer sees the Payment confirmation page, so that the same cart is not paid twice.
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), its open Mollie payment is cancelled at Mollie when Mollie allows it.
The module works with the standard Magento checkout. The customer chooses the Mollie method on the Mollie page, not in your checkout. The module has no subscriptions or recurring payments, no saved cards or mandates, no card fields on your site, no Apple Pay or PayPal express buttons and no Orders API, so methods that need order lines (for example some Klarna, Billie or in3 variants) are not offered by Mollie for these payments. Authorized payments are captured or voided in the Mollie Dashboard, not from Magento. Mollie is not offered for orders created in the Admin or for multi-address checkout.
Orders and refunds
Order statuses
Pending Payment: the order was placed and the customer was sent to Mollie, but Mollie has not confirmed the payment yet, or the customer chose bank transfer and Mollie waits for the money (the note says Awaiting the Mollie bank transfer.). There is no invoice.
Processing or Complete: the payment was confirmed. The status follows Order Status After Payment. The invoice is created with the Mollie payment ID (tr_...) as the transaction ID, and a note shows the Mollie method and the mode.
On Hold: an authorized payment waits for capture, Mollie reported a chargeback, the paid amount or currency differed from the order, or a test payment was paid while the store is in live mode (no money was received). Except for the chargeback, there is no invoice. The note says Mollie payment requires review: and the reason. Check the payment in the Mollie Dashboard, then process the order or refund the payment. When money is at Mollie (an authorized payment or a different amount or currency), the order is moved to Processing before the hold, so Unhold returns it to Processing and Magento does not cancel it as an expired Pending Payment order. If you decide not to keep such an order, release or refund the payment in the Mollie Dashboard (or with Refund uninvoiced charge), then use Unhold and Cancel if the order is still open.
Canceled: the payment was cancelled, failed or expired, the payment could not be started, or the order was cancelled in Magento. If a payment arrives after the order was cancelled, no invoice is created and a note asks you to review it.
Closed: the payment was fully refunded with a credit memo.
If a second payment of the same cart is paid, the order is not changed. A note asks you to refund the duplicate payment in your Mollie Dashboard. The notes are order comments that the customer does not see.
Mollie payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Mollie transaction (the payment ID), Mollie mode, Mollie status, Mollie result and the Mollie refund history. The customer sees only the payment method title. On the Information tab, Admin users who may edit orders also see the Mollie transactions block with all payment attempts of the cart and the button Check Mollie payment status, which reads the payment from Mollie again and adds the result as a note.
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 Mollie. Full and partial refunds are supported. The Comment Text of the credit memo is sent to Mollie as the refund description (up to 140 characters). A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Mollie.
The refund is made in the order currency, up to the amount Mollie charged minus the amounts already refunded. For JPY and ISK the amounts are rounded to whole units, the same way as the payment, so all refunds together never exceed what Mollie charged. The refund is sent for the payment that paid the order, with the API key of the mode it was made in, so that mode's key must be set. If Mollie does not accept the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it on the order with the Mollie refund ID (re_...) as the transaction ID. A full refund closes the order. Refunds are available once Mollie has confirmed the payment and the order has an invoice.
Charges without an invoice: when a payment was received but the order has no invoice (for example On Hold after an amount mismatch, or a test payment while the store is live), the Mollie transactions block shows This charge has no paid invoice. Its actual amount can be refunded without creating a Credit Memo. Enter the Refund amount in the currency Mollie charged (the remaining amount is filled in) and optionally a Reason, and click Refund uninvoiced charge. You need the right to create credit memos. The refund and a note are added to the order; a full refund cancels it.
Refunds created in the Mollie Dashboard are not shown on the order; a chargeback adds a note.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mollie Gateway is the first row of the VibeFox Mollie 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-mollie 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, Mollie 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
Mollie 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 an API key: Test Api Key in test mode, Live Api Key in live mode. Check that the currency the customer pays in is supported by Mollie. 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 cannot reach your store. The URL shown in Setup and webhook must be reachable from the internet (no basic authentication or firewall in the way). The order is also confirmed when the customer returns to the store after paying, when the customer clicks Check again, or when you click Check Mollie payment status on the order.
Webhook answers unknown: the payment was not created by this store, for example a payment of another Mollie account. Nothing is changed.
Webhook answers foreign: the payment does not belong to the cart or the mode it was created for. Nothing is changed.
Webhook answers unavailable or missing key: the Mollie API could not be reached, or the API key of the payment's mode is not set. Mollie retries the webhook later.
Webhook answers busy: the cart was being processed by another request at the same moment. Mollie retries the webhook. Turn on Debug log to see more.
The webhook URL shows Mollie sends a POST payment id. in the browser: this is normal. The URL accepts only requests from Mollie.
Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Mollie retries the webhook later, and the order is also confirmed when the customer returns.
Bank transfer orders are cancelled before the money arrives: the Magento cron cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime. If you offer bank transfer in Mollie, set a longer lifetime in Stores > Configuration > Sales > Sales > Orders Cron Settings. A payment that arrives for a cancelled order is not invoiced; the note asks you to review it.
An API key is not saved: the key must start with test_ or live_ followed by at least 30 letters and digits. Copy it again from the Mollie Dashboard.
The customer is back in the cart with an error after Place Order: turn on Debug log and look at the Log field. It shows the HTTP code and the Mollie message. 401 means a wrong API key; 422 points to a field of the request, for example an amount or currency Mollie does not accept. The order of that attempt is cancelled.
The order is On Hold: read the notes of the order (see Order statuses), then process the order or refund the payment.
Refund fails with Configure the API key of the mode used for this payment.: the payment was made in test or live mode, and the API key of that mode is not set. Enter it and try again.
Refund fails with The Mollie refund journal needs reconciliation before another online refund.: the order already has a refund that was not made through Mollie by the module, for example a Refund Offline credit memo. Refund the rest in the Mollie Dashboard and record it with Refund Offline.
Refund fails with The Mollie refund outcome is unknown. Check the Dashboard before trying again.: Mollie did not give a clear answer. Further online refunds of this order are blocked so that no money is refunded twice. Check the refund in the Mollie Dashboard and, if needed, refund there and record it with Refund Offline.
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 can be refunded with Refund uninvoiced charge (see Refunds) or in the Mollie Dashboard.
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_MolliePayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MolliePayment to remove the data, then bin/magento module:disable Vibefox_MolliePayment, delete the folder app/code/Vibefox/MolliePayment and run bin/magento setup:upgrade.
The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Mollie payment attempts and refund records 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.
Mollie is a trademark of its respective owner. This module is not affiliated with or endorsed by Mollie.