Troubleshooting

Terminal Is Busy

Symptom: Response contains "statusCode": "TERMINAL_BUSY" or "statusMessage": "Terminal Is Busy".

Cause: The terminal is already processing a transaction. Nami terminals can only handle one transaction at a time. A previous transaction may still be in progress or waiting for card tap.

Fix

1. Wait for the terminal screen to return to idle, then retry.
2. If the terminal appears stuck, press Cancel on the terminal keypad.
3. Do not send a new transaction while the terminal shows a payment prompt.

Connection Refused (TCP/IP)

Symptom: Response contains "Failed to establish TCP/IP connection" or the request times out immediately.

Causes and fixes

Cable Disconnected (COM path)

Symptom: Response contains "statusCode": "CableDisconnected".

Cause: The USB cable was physically unplugged from the PC or terminal during communication (or before the transaction was sent).

Fix

1. Reconnect the USB cable firmly.
2. Wait for the COM port to reappear in the dropdown (about 5 seconds).
3. Call /com/connect again before sending a new transaction.

📘

No restart needed

The middleware detects cable disconnection within 1 second using hardware events. You do not need to restart the service.

COM Port Not Showing in Dropdown

Symptom: The COM port dropdown in the dashboard shows "No devices connected" after plugging in the terminal USB cable.

📘

"Reconnecting to COMx..." is not an error

If the dropdown instead shows "Reconnecting to COMx...", the middleware previously had a working connection to that port and is automatically retrying in the background (e.g. right after a cable was unplugged and replugged). No action is needed — wait a few seconds for it to reconnect. After com.reconnect.timeout.minutes (default 2) it switches to "Disconnected — last seen on COMx" while still retrying silently — plug the device back in at any point and it reconnects automatically. If it never reconnects, see the causes below.

Causes and fixes

Registration Required

Symptom: Response contains "REGISTER_REQUIRED" or "Registration Required".

Cause: Your POS (or test session) sent a financial transaction without first completing a REGISTER transaction in this session.

Fix

1. Send a REGISTER transaction first.
2. Wait for "statusCode": "200" before sending any purchase, refund, or other transaction.
3. Registration is normally per session — however, the middleware now persists Terminal ID registrations and restores them automatically after a service restart, along with the last-used COM connection and any active TCP/IP connections (see Connection persistence & auto-reconnect). If you still see REGISTER_REQUIRED after a restart, the terminal's own session may have been reset — send REGISTER again.

Transaction Timeout

Symptom: Response contains "statusCode": "TIMEOUT" and "Transaction timed out after 30s".

Cause: The terminal did not respond within the configured timeout (default: 30 seconds). This can happen if:

• The card was not presented to the terminal in time.
• The terminal lost network connectivity mid-transaction (TCP/IP).
• The USB cable was pulled during the transaction (COM).
• The terminal is unresponsive or locked.

Fix

1. Ensure the cardholder is ready to tap/insert their card before initiating the transaction.
2. Check the network connection (TCP/IP) or cable (COM).
3. If the timeout is too short for your use case, increase ecr.transaction.timeout.seconds in application.properties and restart the service.
4. Send a REVERSAL if a transaction was partially sent to the terminal.

SSL / Browser Certificate Warning

📘

Applies only when HTTPS is enabled

This section only applies if HTTPS has been enabled via the dashboard's Diagnostics → Service Health → "Switch to HTTPS" toggle. By default the middleware serves plain HTTP on http://localhost:9099, which has no certificate warning.

Symptom: Chrome or Edge shows "Your connection is not private" when opening https://localhost:9099.

Cause: Switching to HTTPS generates a self-signed certificate for localhost. Browser trust for this certificate is separate from the OS trust store.

Fix (Chrome / Edge)

1. Click Advanced.
2. Click Proceed to localhost (unsafe).
3. The warning will not reappear.

Fix (Postman)

1. Go to Settings → General.
2. Disable SSL certificate verification.

If the warning reappears after reinstalling: the old certificate may have been removed but the new one not yet trusted by the browser. Restart the browser after reinstalling.

"Access Denied" in Tray App

Symptom: Tray app shows a balloon notification: "Access denied — run the tray app as Administrator."

Cause: The Windows service DACL (permission entry) that allows non-admin users to start/stop the service was not set — this happens only if you installed v1.4 or earlier, or if the DACL was manually removed.

Fix — Option 1 (recommended): Reinstall
Run the latest installer (v1.5 or later) as administrator. The installer sets the DACL automatically.

Fix — Option 2: Manual command
Open a Command Prompt as Administrator and run:

sc sdset NamiMiddleware "D:(A;;CCLCSWRPWPDTLOCRRC;;;SY)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;BA)(A;;CCLCSWRPWPLOCRRC;;;IU)(A;;CCLCSWRPWPLOCRRC;;;SU)"

After running this command, the tray app can start and stop the service without UAC prompts.

Arabic Locale — Amount Showing as ????????????

Symptom: The terminal displays question marks in the amount field, or returns an amount error, on Windows machines with Arabic (Saudi Arabia) regional format settings.

Cause: This was a bug in v1.4 and earlier. The String.format call used to build the terminal packet was sensitive to the system locale — Arabic (ar_SA) regional format produces Arabic-Indic digits (٠١٢٣...) instead of ASCII digits (0123...). The terminal only accepts ASCII, so the conversion produced ? bytes.

Fix: Update to v1.5 or later. The fix forces Locale.ROOT in the amount formatter so the output is always ASCII digits regardless of system regional settings.

Tray Icon Shows Red But Service Is Running

Symptom: The tray icon is red (indicating service stopped), but Windows Services shows the NamiMiddleware service as "Running".

Cause: The tray app polls the /api/health-status endpoint to determine status. If the tray app lost its connection to the service (e.g. the service was briefly unreachable during a restart), it may show a stale state.

Fix

1. Right-click the tray icon and choose Exit Tray.
2. Relaunch the tray app from the Start menu (Nami Middleware group) or from C:\Program Files (x86)\Nami Middleware\jre\bin\javaw.exe -jar Nami-Tray-App.jar.
3. The tray app will re-poll within 5 seconds and show the correct state.

Service Not Starting

Symptom: After installation, or after clicking "Start Service" in the tray app, the service does not start and no dashboard is accessible.

Checks

1. Open Windows Event Viewer → Windows Logs → Application and look for errors from NamiMiddleware or Java.
2. Check C:\Program Files (x86)\Nami Middleware\logs\ for application log files — startup errors are logged there.
3. Verify that port 9099 is not already in use by another application:
   • Open Command Prompt and run: netstat -ano | findstr :9099
   • If another process is using the port, either stop it or change server.port in application.properties.
4. Make sure the JRE is present at C:\Program Files (x86)\Nami Middleware\jre\bin\java.exe. If it is missing, reinstall.

Getting further help

If none of the above resolves your issue:

1. Go to the Diagnostics → Log Archives tab in the dashboard and download the most recent log file.
2. Contact Nami support and attach the log file along with a description of the problem.