Payment terminal settings

The Payment Terminal tab pairs Fexl Lite to a Nebula card terminal — the physical device the customer taps or inserts a card into. Once configured, card-payment checkouts at POS route through the terminal automatically: amount pushed to the device, card processed, success / fail returned to Fexl Lite. The cashier never types a number into the terminal directly.

Updated 5 May 2026·For v2.2.0·5 min read

ⓘ

Tauri desktop only

Terminal integration needs hardware access (USB COM port) and a long-lived background poller — both Tauri-only capabilities. The web app’s checkout falls back to “Charge on terminal” being a manual step the cashier confirms after typing the amount themselves. If you do real card volume, install the desktop.

settings · payment terminal · Nebula USB / WiFi / cloud connection panel

Connection modes

Three modes, picked in the Connection dropdown. Same Nebula device, different transport.

Mode	When you’d use it	Fields
USB	Terminal cabled directly to the desktop	COM port (Windows: COM3; macOS / Linux: /dev/tty.usbserial-...)
Wi-Fi	Terminal on the same LAN, talking HTTP	Host (IP), port (default 5000)
Cloud	Terminal anywhere, paired through Nebula’s cloud relay	Pairing code (8 chars) + EID (the device’s serial-number-like ID)

USB is the most reliable; cloud is the most flexible. Wi-Fi is the middle ground — works well on a stable LAN, less well over a noisy guest Wi-Fi.

Pairing the terminal

1

Pick a connection mode

USB if cabled. Wi-Fi if same LAN. Cloud if neither — you’ll need a pairing code from Nebula’s portal.

2

Fill the fields

USB: pick the COM port from the dropdown (Fexl Lite enumerates them on focus). Wi-Fi: type the IP and port. Cloud: paste the pairing code and EID — both come from the Nebula admin once you register the device.

3

Set the base URL

An advanced field — the Nebula API endpoint to talk to. Defaults to the production URL. Override only if you’re testing against Nebula’s sandbox or a self-hosted gateway.

4

Test connection

Click Test connection. Fexl Lite opens a session, requests the terminal status, and shows a green check on success. Failure messages spell out what went wrong — wrong COM port, terminal offline, pairing code already used.

5

Save

The config is stamped against this device only. If the till has two desktops with two terminals, each pairs independently.

How a card payment runs

When the cashier picks Card at checkout and the terminal is configured:

1. The checkout dialog shows a Charge on terminal button. The amount and reference (invoice number) are pre-filled.
2. Click triggers a POST /transactions to the Nebula endpoint with the amount and reference.
3. The terminal beeps, displays the amount, and waits for the customer to tap or insert.
4. Fexl Lite polls the transaction’s status every 1.5 seconds. The dialog shows live state: Waiting for card → Processing → Approved / Declined.
5. On approval, Fexl Lite stamps the invoice with the terminal’s transaction ID and last-4 of the card. On decline, the cashier can retry or fall back to cash.

The whole flow is async with a 60-second timeout. If the customer wanders off mid-tap, the cashier hits Cancel and the terminal reset request fires.

Refunds from the terminal

When a return is processed against an invoice paid by card, Fexl Lite can push the refund back through the same terminal rather than handing back cash — keeping the books straight and the customer’s card whole. The Returns wizard surfaces a Refund to card option when the source invoice’s terminal transaction ID is on file. The terminal beeps for the customer to re-present their card; the refund posts on confirmation.

!

Refund-to-card needs the original transaction ID

If the original invoice was paid in cash and the customer wants a card refund, you can’t — the chain isn’t there. Same the other way. The card the refund lands on must be the card the original paid with. This is a Nebula constraint, not a Fexl Lite limitation.

Troubleshooting

A few things that come up often:

• Test connection fails over USB — wrong COM port (Windows reuses port numbers across devices; check Device Manager) or the terminal’s serial driver isn’t installed. macOS users sometimes need to allow the Nebula USB driver under Privacy & Security.
• Wi-Fi terminal goes intermittent — almost always the network. Pin the terminal’s IP statically; check the router doesn’t sleep its 2.4 GHz band.
• Cloud pairing rejects the code — codes are single-use and expire after 10 minutes. Generate a fresh one from Nebula’s admin portal and try again.
• Polling times out without a verdict — the terminal disconnected mid-transaction. Most rare. Check the Nebula admin’s transaction list to see if the charge actually went through; if it did, mark the invoice paid manually and call support.

Related

NEBULA

Nebula deep dive

Full pairing flow, the API contract, and the refund-from-terminal walkthrough.

POS

Card payments at POS

What the cashier sees when the terminal is wired up and a card payment runs.

PRINTER

Receipt printer

The other Tauri-only hardware tab.

RETURNS

Returns and refunds

When refund-to-card kicks in and what happens if it can’t.