Nebula payment terminal

Nebula is the card terminal Fexl Lite knows how to drive directly. Once paired, a card-payment checkout at POS sends the amount straight to the terminal — the cashier never types it in, the customer taps or inserts, and the terminal hands the result back. This page covers the full pairing flow, the handshake that establishes a session, the per-transaction polling loop, and the refund-from-terminal flow that closes the loop on returns.

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

ⓘ

Tauri desktop only

Driving the terminal needs a long-lived background poller and direct USB / network access — both Tauri-only. The web app falls back to “Charge on terminal” being a manual prompt.

integrations · nebula · pairing flow with terminal screenshot

The three connection modes

Nebula speaks the same protocol regardless of how it’s reached. The connection mode just changes the transport.

Mode	When to pick it	Latency	Reliability
USB	Cabled to a counter-stationed desktop	<50 ms round-trip	Highest — no network in the loop
Wi-Fi	Same LAN as the desktop, cordless terminal at the till	50-200 ms	High on stable LAN, drops with congestion
Cloud	Terminal anywhere, paired through Nebula’s relay	200-500 ms	Depends on both endpoints’ connectivity

Most counter setups pick USB. Mobile sales (delivery driver, market stand, food truck) pick Wi-Fi or cloud.

Pairing — the handshake

Pairing happens once per desktop-to-terminal pair. The flow:

1

Register the terminal in Nebula's portal

Sign in to the Nebula admin (or onboarding portal) → Devices → Add new → enter the terminal’s serial / EID. The portal returns a one-time pairing code (8 chars) and the EID for cloud-mode connections.

2

Pick the connection mode in Settings → Payment Terminal

USB / Wi-Fi / Cloud. Each mode reveals its own field set — see Payment terminal settings for the per-mode field reference.

3

Save and test

On save, Fexl Lite opens a session with the Nebula API: it presents the pairing code (cloud mode) or the local route (USB / Wi-Fi), the API issues a session token, and Fexl Lite stamps the token plus the EID against this device. The session token is good for 24 hours and rolls automatically.

4

Run a $0.01 test charge

Ring a sale for the smallest amount your processor accepts (usually $0.01 or its currency equivalent), pick Card, complete on the terminal, void the invoice afterwards. End-to-end smoke test in 60 seconds.

What the terminal returns

When a transaction completes, the Nebula API returns a payload Fexl Lite stamps onto the invoice:

• Transaction ID — Nebula’s UUID for the charge. Required for any future refund against this invoice.
• Last-4 — last four digits of the card. Prints on the receipt’s payment-summary line.
• Card type — Visa, MasterCard, Mada, etc. Cosmetic only.
• Approval code — short alphanumeric returned by the issuer. Useful for chargeback disputes.
• Receipt blob — optional, pre-formatted card-receipt text Fexl Lite appends to the customer’s printed receipt for compliance.

The transaction ID is the load-bearing field. Without it, the refund-to-card path can’t reach the right charge to reverse.

Polling loop, in detail

The desktop polls the transaction status every 1.5 seconds while the customer is at the terminal:

POS → Nebula:  POST /transactions  { amount, reference, sessionToken }
                ↓
                returns { transactionId, status: "pending" }
POS → Nebula:  GET /transactions/{id}  every 1.5s
                ↓
                status: pending → processing → approved | declined | timeout

The dialog updates state live: Waiting for card → Processing → Approved or Declined. The full timeout is 60 seconds — past that, Fexl Lite cancels the transaction at Nebula’s end and reports a soft failure to the cashier (try again or fall back to cash).

!

Don't refresh the POS during a card transaction

The polling loop is page-scoped — refreshing the POS while a card payment is mid-flight breaks the link. The terminal still completes the charge, but the invoice doesn’t get marked paid until you reconcile manually. Wait for the verdict, even if it takes 45 seconds.

Refunds from the terminal

When a return is processed against an invoice paid via Nebula, Fexl Lite can push the refund back through the same terminal rather than handing back cash. The chain:

1. The Returns wizard checks the invoice’s stamped transactionId. Present → refund-to-card option appears.
2. The cashier picks Refund to card. Fexl Lite sends POST /refunds with the original transaction ID and the refund amount.
3. The terminal beeps for the customer to re-present their card.
4. On approval, the refund posts and the customer’s card is credited within 1-3 business days (per the issuer; nothing Fexl Lite or Nebula control).

Partial refunds work — refund less than the original transaction. Multiple refunds against the same transaction work too, until the cumulative refund amount equals the original charge.

ⓘ

Refund must use the original card

The card credited has to be the card originally charged. This is a network-rules constraint (Visa / MasterCard prevent cross-card refunds for fraud reasons), not a Fexl Lite limitation. If the original card is gone (cancelled, lost), the only option is a cash or store-credit refund instead.

Where things break

Five common failure modes:

• Pairing code expired — Nebula codes are single-use and live 10 minutes. Generate a new one from the portal.
• Wi-Fi terminal goes intermittent — pin the terminal’s IP statically, check the router doesn’t sleep its 2.4 GHz band.
• USB COM port drifts — Windows reuses port numbers. After a USB unplug-replug, the terminal might come back as COM4 instead of COM3. Re-pick from the dropdown.
• Polling times out without a verdict — terminal disconnected mid-transaction. Check Nebula’s portal transaction list to see if the charge cleared; if so, mark the invoice paid manually.
• Refund-to-card rejected — original transaction is too old (most networks limit refunds to 180 days), or the cumulative refund amount exceeds the original charge. Use store credit instead.

For deeper troubleshooting, see Connection issues.

Related

SETTINGS

Payment terminal config

The in-app tab where the connection mode and credentials are entered.

POS

Card payments at POS

What the cashier sees during a card transaction.

RETURNS

Returns and refunds

Where the refund-to-card path actually fires.

HELP

Connection troubleshooting

When the terminal won’t pair or charges hang.