Mollie Terminal Gateway

The Mollie Terminal gateway lets you take in-person payments on Mollie Terminal hardware directly from WCPOS. A payment is started from WooCommerce and completed on the terminal, and Mollie's confirmation is written back to the order.

Features

Hardware Integration

Send payments to Mollie terminals registered on your Mollie account and collect card-present payments

No Manual Pairing

Terminals are fetched live from your Mollie account — pick one from a dropdown, no device ID to paste

Reliable Completion

Payments are confirmed by polling Mollie, and the POS redirects to the receipt automatically once the terminal confirms

Secure Transactions

PCI-compliant, card-present processing handled on Mollie hardware

Refunds Supported

Refund from the WooCommerce order screen, reconciled against Mollie so refunds are never duplicated

How It Works

Mollie Terminal uses Mollie's server-side pointofsale payments. When you start a payment, WooCommerce creates a Mollie payment for the order and Mollie pushes it to the selected terminal. The customer pays on the device, and Mollie is the source of truth for payment and refund state — the local WooCommerce order meta is only a cache.

How a payment is confirmed. While the payment is in progress the POS polls Mollie (every 2 seconds by default) and, when the terminal confirms, redirects straight to the thank-you page. Mollie webhooks are also used to speed this up — and the webhook URL is set automatically on every payment, so there is nothing to configure in the Mollie dashboard.

The terminal must be registered and active on the same Mollie account as the plugin.

Setup

1

Install Mollie Terminal for WooCommerce

Install from WP Admin > POS > Settings > Extensions, or download the latest plugin zip asset (not the GitHub source-code zip or tarball) from the GitHub releases page and upload it via Plugins > Add New > Upload Plugin.

2

Configure your Mollie credentials

1. Go to WP Admin > WooCommerce > Settings > Payments and open Mollie Terminal
2. Set Mode to Live — terminal payments require a live account (see Scope & Limitations)
3. Set API key source to reuse the key from the official Mollie Payments for WooCommerce plugin, or use the key entered on this screen
4. If you enter the key here, paste your Mollie live API key into Mollie API Key
5. Save

Use Live mode

Mollie terminals exist only on live accounts, so the test API key cannot drive a terminal. The settings screen warns you when Test mode is selected — switch to Live with your live API key to take payments. See Scope & Limitations.

No Profile ID needed

pointofsale payments do not require a Mollie Profile ID, and terminals are listed across the whole account, so there is nothing else to paste.

3

Choose your terminals

1. Pick a Default terminal from the dropdown. The list is fetched from the selected Mollie environment — inactive terminals are hidden, because Mollie cannot reactivate them.
2. (Optional) Restrict Enabled terminals to the devices actually in use. The saved default remains available even if it is not selected here; leave the setting empty to allow all active terminals. To retire a terminal, also change or clear Default terminal.
3. (Optional) Enable Lock terminal selection so cashiers cannot change the terminal at checkout — the default terminal is always used, and this is enforced on the server too.
4. Save

4

Enable in WCPOS

1. Go to WP Admin > POS > Settings > Checkout
2. Find the Mollie Terminal gateway and enable it for the POS
3. Save your settings

opmerking

The Enable/Disable checkbox on the WooCommerce settings screen controls the online store checkout only. WCPOS uses this gateway once it is configured, whether or not that box is ticked.

Settings reference

Setting	What it does
Enable/Disable	Enables the gateway for the online store checkout (not required for POS)
Title / Description	Label and text shown to the customer at checkout
Mode	Test or Live. Terminal payments require Live — the test API key cannot drive a terminal
API key source	Uses the key entered below, or reuses the matching test/live key from the official Mollie Payments for WooCommerce plugin. If the shared key is unavailable, the plugin falls back to the key below
Mollie API Key	The test or live API key for the selected mode. Used when API key source is set to the key entered here, and as the fallback for a missing shared key
Default terminal	The terminal used by default at checkout, chosen from a dropdown of active terminals in the selected Mollie environment
Enabled terminals	Restricts the checkout list to selected terminals. Empty = all active terminals. The saved default is always available, so change or clear it too when retiring a terminal
Lock terminal selection	Forces the default terminal at checkout so cashiers cannot change it (requires a default terminal)
Checkout debug logs	Shows the Show logs, Copy, and Clear tools on the checkout payment panel. Leave this off unless gathering logs for support; payment activity is always recorded under WooCommerce > Status > Logs

The webhook URL is applied automatically on every payment, so there is no webhook field to fill in and no Mollie dashboard configuration required.

Usage

Processing Payments

1. Add Items: Add products to your cart in the POS
2. Select Gateway: Choose "Mollie Terminal" as the payment method
3. Choose Terminal: Pick a terminal from the dropdown (defaults to the configured one; hidden if terminal selection is locked)
4. Start Payment: Click Start Terminal Payment — Mollie pushes the payment to the device
5. Customer Payment: The customer taps, inserts, or swipes their card on the terminal. The status updates live — Sending to terminal… → Waiting for terminal…
6. Automatic Completion: When the terminal confirms, the order is marked paid and the POS redirects to the receipt automatically

Payment Controls

• Start Terminal Payment: Send a new payment request to the selected terminal
• Cancel Payment: Cancel a payment that is still open. Once the payment has reached the terminal Mollie reports it as no longer cancelable, and the cashier cancels on the device itself

Order Management

• Verified completion: Every webhook, poll, cancel, and retry fetches authoritative Mollie state before changing an order, so orders are marked paid only on confirmed Mollie state
• Payment Tracking: Payment attempts are recorded as append-only history on the order
• Receipt Generation: Standard POS receipts are generated after successful payments

Refunds

Refunds are supported. Refund an order from the normal WooCommerce order screen and the refund is sent to Mollie. Because Mollie is the source of truth, refund retries reconcile against Mollie's refund IDs and metadata before creating another refund, so a refund is never accidentally issued twice.

Stale payment cleanup

A Mollie pointofsale payment can stay "open" on Mollie's side if a checkout is abandoned. The plugin cancels these open payments automatically when:

• the auto-poll times out (5 minutes by default) — the cancel is sent instead of leaving the payment behind
• the order is completed with a different payment method (for example the customer pays cash instead), or the order is cancelled in WooCommerce
• the checkout page is closed mid-payment — a best-effort cancel fires as the tab leaves
• a WP-Cron sweep runs every 10 minutes and cancels or resolves payments left open past the stale threshold (10 minutes by default), including when the browser closes or the network drops before the other cleanup paths run

If the payment already reached the terminal, Mollie reports it as not cancelable and the cashier cancels on the device itself — these cleanups are safe no-ops in that case.

Requirements

Mollie Account: Active Mollie account with a live API key

Compatible Hardware: A Mollie Terminal device, active on that Mollie account

Currency: EUR — POS terminal payments are limited to EUR for now

WCPOS: Pro version required for POS checkout

Stable Connection: Reliable internet connection for API communication

Scope & Limitations

Test mode limitation

Mollie terminals exist only on live accounts. The Mollie test API key cannot drive a physical (or iOS/Android) terminal, so terminal payments cannot be exercised end-to-end in test mode. This is a Mollie platform limitation, not a plugin restriction — the settings screen shows a warning when Test mode is selected. Use Live mode with your live API key to take terminal payments.

Currency

POS terminal payments are limited to EUR until broader Mollie Terminal currency support is confirmed.

Troubleshooting

Common Issues

No terminals appear in the dropdown

• Confirm Mode is set to Live and the effective API key is a live key — terminals do not exist on test accounts
• Check the terminal is registered and active on your Mollie account; inactive terminals are hidden because Mollie cannot reactivate them
• Make sure your site can reach Mollie — the list is fetched live over the API

Payment won't start

• Confirm a terminal is selected (or a Default terminal is set when selection is locked)
• Check the terminal is powered on, online, and active on the same Mollie account
• Verify the order currency is EUR

The terminal timed out or the payment stayed open

• The plugin attempts to cancel open payments automatically on timeout (5 minutes by default)
• If the payment already reached the terminal and cannot be cancelled automatically, cancel it on the device itself
• You can then start a fresh payment or take payment another way

Order completed on the terminal but is slow to update

• The POS polls Mollie every 2 seconds and redirects when the payment confirms; a webhook usually confirms it first
• Because Mollie is the source of truth, the order is reconciled against authoritative Mollie state — it is not lost
• Check WooCommerce > Status > Logs for any Mollie API messages

Getting Help

For technical support:

• Visit the GitHub repository to report issues
• Check the Mollie Terminal setup guide and the Mollie Create Payment API for API-related questions
• Contact Mollie support for account and hardware issues

Screenshots

Screenshots will be added in a future update to show:

• The Mollie Terminal settings screen — API key, default terminal, and enabled terminals
• Gateway enablement in WCPOS settings
• Payment processing workflow in the POS checkout