Testing via the Dashboard

The Nami Middleware Health Dashboard lets you test transactions, monitor terminal connections, and view logs — all from your browser, without writing any code.

URL: http://localhost:9099

📘

Before you start

Make sure the service is running (the tray icon should be amber or green). If you've enabled HTTPS via the Diagnostics → Service Health toggle, use https://localhost:9099 instead — see HTTPS (optional) for the certificate warning.

Dashboard layout

The dashboard has four tabs along the top:

Terminal Testing tab

This is where you run test transactions. The tab has two sub-tabs: TCP/IP and COM.

TCP/IP path

Use this when your terminal connects over Wi-Fi or a network cable.

Step 1 — Enter connection details

Step 2 — REGISTER

1. With your terminal powered on and connected to the network, click REGISTER.
2. The terminal screen will show a registration prompt — confirm on the terminal.
3. Wait for the response panel to show statusCode: 200.

🚧

REGISTER must succeed first

REGISTER must succeed before running any other transaction. If you skip it, subsequent transactions will fail with a "Registration Required" message.

Step 3 — Run a transaction

1. Select a transaction type from the dropdown (e.g. PURCHASE).
2. Enter the amount in SAR (e.g. 10.00 for SAR 10).
3. Click Send.
4. Follow the prompt on the terminal (tap/insert card, enter PIN if required).
5. The response panel shows the result.

Step 4 — Disconnect (when finished)

Click Disconnect to cleanly close the TCP/IP connection.

COM (USB) path

Use this when the terminal is connected to the PC by USB cable.

Step 1 — Select the COM port

1. Plug in the USB cable between your terminal and the PC.
2. The COM Port dropdown auto-refreshes every 5 seconds — wait a moment and you should see the device appear (e.g. COM3 - USB Serial Device).
3. If no device appears, check that the USB driver was installed (see COM Port Not Showing in Dropdown).

Step 2 — Set connection parameters

The recommended settings for Nami terminals are:

Step 3 — Connect

Click Connect. A green "Connected" badge appears next to the port name. The tray icon also turns green.

Step 4 — REGISTER

Same as the TCP/IP path — click REGISTER and confirm on the terminal. Wait for statusCode: 200.

Step 5 — Run a transaction

Select a transaction type, enter the amount, and click Send.

Step 6 — Disconnect

Click Disconnect to release the COM port.

Response panel

After each transaction, the response panel on the right shows the terminal's reply.

• Raw response: the semicolon-delimited string received from the terminal.
• Parsed response: a human-readable breakdown with labelled fields (shown when the JSON Response toggle is on).

A successful transaction shows "statusCode": "200" and a "statusMessage": "Approved" (or similar approval text).

Using the built-in Simulator

The Simulator lets you test the full transaction flow without a physical terminal — TCP/IP only (COM is not supported by the Simulator). There are two independent modes, both controlled from the Terminal Testing → TCP/IP sub-tab. Know which one you're using, since they behave very differently.

Mode 1 — In-browser mock (no server, instant)

Toggle Enable Nami Terminal Simulator on and just click Run Transaction. This runs entirely in your browser — it never starts a TCP listener and never calls the backend. It's useful for quickly demoing the transaction flow (the phone-screen animation) without any setup, but the response is a client-side fabrication, not a real terminal round-trip.

Mode 2 — Real TCP Simulator (a genuine terminal-protocol listener)

This is a real socket server any TCP/IP client can connect to — Postman, this same dashboard (with the in-browser checkbox left unchecked), or a third-party ECR client.

1. Go to the Terminal Testing → TCP/IP sub-tab.
2. In the Simulator widget, set a Port (default 8888, or the value of simulator.tcp.port in application.properties) and click Start Server. The badge shows "Listening on :8888" once it's up; Start stays disabled while it's running.
3. In the Connection panel, enter IP 127.0.0.1 and the same Port, then run REGISTER followed by any transaction type — leave Enable Nami Terminal Simulator unchecked so the request actually goes through this real listener.
4. Card-type transactions (Purchase, Refund, UPI, Authorization, Cash Advance) pause and wait for you to choose an outcome in the green "Waiting for card" panel: Tap Card (Approve), Timeout (no card), or Decline with reason (pick a decline code from the dropdown). Non-card transactions (Reconciliation, Reversal, etc.) respond immediately.
5. Click Stop to shut the listener down when you're done.

🚧

Simulator is for testing only

The Simulator is for development and testing only. Do not point a live POS at the Simulator port.

CORS tab

If your POS web application is hosted on a different domain or port than localhost:9099, you may need to add your origin to the CORS allow-list.

1. Open the CORS tab.
2. View the current list of allowed origins.
3. To add a new origin, edit application.properties and update cors.urls, then restart the service.

The default value * allows all origins, which is fine for a local machine where access is already restricted by the firewall.

Diagnostics tab

The Diagnostics tab has three sections accessible from the left sidebar.

Health

Shows live service metrics:

📘

COM dropdown during reconnect

If a USB cable is unplugged and replugged, the COM dropdown briefly shows "Reconnecting to COMx..." while the middleware retries the connection in the background, instead of "No devices connected". If it stays disconnected for longer than com.reconnect.timeout.minutes (default 2), the label switches to "Disconnected — last seen on COMx". The middleware keeps retrying silently either way, and the dropdown reflects the live port again the moment it reconnects.

Live Logs

Streams the middleware application log in real time.

• Use the INFO / WARN / ERROR / DEBUG filter pills to show only the log levels you care about.
• Use the Search box to filter by keyword.
• Click Pause to stop the stream temporarily (useful when reading a specific line).
• The scroll automatically follows new log entries. Click Pause to stop auto-scroll.

Log Archives

Lists log files written to C:\Program Files (x86)\Nami Middleware\logs\. Click any file to download it for offline review or to share with support.