# Mollie Terminal Gateway

The Mollie Terminal gateway lets you take in-person payments on [Mollie Terminal](https://www.mollie.com/products/point-of-sale) 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[​](#features "رابط مباشر إلى 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[​](#how-it-works "رابط مباشر إلى 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[​](#setup "رابط مباشر إلى 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](https://github.com/wcpos/mollie-terminal-for-woocommerce/releases) 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](#scope-and-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](#scope-and-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

ملاحظة

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[​](#settings "رابط مباشر إلى 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[​](#usage "رابط مباشر إلى Usage")

### Processing Payments[​](#processing-payments "رابط مباشر إلى 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[​](#payment-controls "رابط مباشر إلى 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[​](#order-management "رابط مباشر إلى 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 "رابط مباشر إلى 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[​](#stale-payment-cleanup "رابط مباشر إلى 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[​](#requirements "رابط مباشر إلى 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[​](#scope-and-limitations "رابط مباشر إلى 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[​](#troubleshooting "رابط مباشر إلى Troubleshooting")

### Common Issues[​](#common-issues "رابط مباشر إلى 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[​](#getting-help "رابط مباشر إلى Getting Help")

For technical support:

* Visit the [GitHub repository](https://github.com/wcpos/mollie-terminal-for-woocommerce) to report issues
* Check the [Mollie Terminal setup guide](https://docs.mollie.com/docs/setting-up-terminal) and the [Mollie Create Payment API](https://docs.mollie.com/reference/create-payment) for API-related questions
* Contact Mollie support for account and hardware issues

## Screenshots[​](#screenshots "رابط مباشر إلى 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