VibeFox Mollie for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

Store currency: 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 site: Mollie sends webhooks to your store, so the site must be reachable from the internet. Without webhooks, orders are still updated 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_. The payment methods themselves are enabled in your Mollie 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_mollie_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Mollie > 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. Enter your test and live API keys (see Configuration). No webhook has to be configured in Mollie.

6. Turn on Enable/Disable. Leave Test Mode on until you have made a test payment, then untick it.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Mollie. Above the fields the page warns you when Mollie is enabled but the API key of the current mode is empty, and when Mollie does not support the store currency. In both cases the payment method is hidden at checkout. In the list of payment methods, Mollie is marked as needing setup until the current mode has an API key and shows Test mode while test mode is on.

When you save, an API key that does not start with test_ or live_ followed by at least 30 letters and digits is not saved: an error is shown and the previous value is kept.

Checkout

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

Title: the payment method title displayed to the customer during checkout. Default: Mollie.

Description: the payment method description displayed to the customer during checkout. Default: Pay securely via Mollie.

API keys

Find your API keys in Mollie Dashboard > Developers > API keys. No webhook setup is needed: the plugin sends its webhook URL with every payment. The URL is shown in this section and looks like https://your-site/?wc-api=molg_mollie_webhook. It must be reachable from the internet, otherwise orders are updated only when the customer returns from Mollie.

Test Mode: Enable 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 (paid, failed, cancelled, expired). Customers see Test mode: no real payment will be made. at checkout. Payments made in the other mode keep using the key of their own mode for status checks and refunds. Default: on.

Test API Key: your Mollie test API key (starts with test_).

Live API Key: your Mollie live API key (starts with live_).

Orders

Order Status After Payment: the order status to set after a successful payment. The status is set in one step, without a second status change.

Processing: the WooCommerce default (default). Orders with only virtual downloadable products become Completed.

Completed: every paid order becomes Completed.

Advanced

Logging: Enable debug logging writes API calls and webhooks to WooCommerce > Status > Logs, source wcp_mollie_gateway. Errors are always logged. API keys and customer data are never logged. Default: off.

Delete Data on Uninstall: Remove the plugin settings and logs when uninstalling. When checked, the plugin settings and its log files are deleted when the plugin is deleted. Mollie payment IDs stored on orders are kept. Default: off.

Checkout

The customer chooses the payment method (by default Mollie) and places the order. The plugin 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 plugin never trusts a webhook as such: it fetches the payment from the Mollie API with your own API key, checks that the payment belongs to the order and compares the paid amount and currency with the order. The order is marked paid only after Mollie confirms it this way. The plugin handles these Mollie payment statuses:

paid: the payment was made. The order is marked paid when the amount and currency match.

authorized: the payment was authorized but not captured. The order is put on hold with a note; capture it in the Mollie Dashboard.

open (bank transfer): Mollie waits for the money. The order is put on hold, so WooCommerce does not cancel it as unpaid.

open, pending: the payment is not finished yet. The order does not change.

failed, expired, canceled: the latest payment attempt did not succeed. An unpaid order is marked Failed.

chargeback: Mollie reports a charged-back amount. A note is added and the order is put on hold.

When the customer comes back, the plugin checks the latest payment with the Mollie API the same way. A paid payment leads to the order received page. If the payment was cancelled, failed, expired or not finished, the customer goes to the Pay for order page with a message, for example You cancelled the Mollie payment. You can try again or choose another payment method. or The Mollie payment has expired. Please try again or choose another payment method.

When the customer pays again, the still-open Mollie payment of the same amount is reused instead of creating a second payable one. If the order total changed, the old open payment is cancelled at Mollie when Mollie allows it. If the old payment was paid meanwhile, the order is marked paid without a new payment.

If Mollie cannot start the payment, the customer sees a short message, for example The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (wrong API key) or Mollie cannot accept a payment of this amount or currency. Please choose another payment method. The technical reason is added to the order notes and the log.

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 customer chooses the Mollie method on the Mollie page, not in your checkout. The plugin has no subscriptions or recurring payments, no saved cards or mandates, no Mollie Components (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 WooCommerce.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Mollie and has not paid yet.

Processing or Completed: the payment was confirmed. The status follows Order Status After Payment. The order note shows the Mollie payment, the method and the mode. The transaction ID is the Mollie payment ID (tr_...) that paid the order.

On hold: a bank transfer waits for the money, an authorized payment waits for capture, or Mollie reported a chargeback. On hold is also set when the paid amount or currency differed from the order, when a test payment was paid while the store is in live mode (no money was received), or when the payment arrived after the order had been cancelled. The order note explains it. Check the payment in the Mollie Dashboard, then process the order or refund the payment.

Failed: the latest payment attempt failed, expired or was cancelled. A paid order is never changed. The customer can pay again.

If a second payment of the same order is paid, the order is not changed again. A note asks you to refund the duplicate payment in your Mollie Dashboard.

Refunds

Open the order, click Refund, enter the amount and click Refund via Mollie (the button shows your Title). Full and partial refunds are supported. The refund is sent for the payment that actually paid the order, with the API key of the mode it was made in, so that mode's key must be set. The button is available only for orders with a paid Mollie payment. If Mollie rejects the refund, WooCommerce shows Mollie's error message and no refund is recorded. A successful refund is added to the order notes with the Mollie refund ID.

Refunds and chargebacks created in the Mollie Dashboard are not turned into WooCommerce refunds. A chargeback adds a note.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Mollie. 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, Mollie 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

Mollie does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has an API key: Test API Key in test mode, Live API Key in live mode. Check that the store currency (or the order currency on the Pay for order page) is supported by Mollie. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: the webhook cannot reach your site. The webhook URL shown in the settings must be reachable from the internet (no maintenance mode, basic authentication or firewall in the way). The order is also updated when the customer returns to the store after paying.

Webhook answers Unknown payment.: the payment ID is not known to Mollie for your test or live API key, for example a payment of another Mollie account.

Webhook answers Payment ID mismatch.: the payment does not belong to the order in its data. The order is not changed.

Webhook answers Failed to fetch payment.: the Mollie API could not be reached. Mollie retries the webhook later.

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 payment is not created: the order note and the log show 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. Turn on Logging and look at WooCommerce > Status > Logs, source wcp_mollie_gateway.

The order is On hold: read the order note. The reason is a mismatch of amount or currency, a test payment in live mode, a payment after cancellation, a bank transfer, an authorization without capture or a chargeback.

Refund fails with a message about the mode: the payment was made in test or live mode, and the API key of that mode is not set. Enter it and try again.

Other currencies: developers can change the currency list with the molg_supported_currencies filter.

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 and the log files are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, Mollie payment IDs and transaction IDs.

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