Local API Middleware (REST)
What the Nami Local API Middleware does, how it talks to your terminal, and the session sequence every integration must follow.
Nami Local API Middleware is a Windows service that sits between your Point-of-Sale (POS) system and your Nami payment terminal. Your POS sends a simple HTTP request to the middleware; the middleware communicates with the terminal and returns the result.
Base URL: http://localhost:9099
HTTP by default — HTTPS is optional
The middleware serves plain HTTP on port 9099, so there are no certificate warnings out of the box. If you need HTTPS, open the dashboard's Diagnostics → Service Health tab and use the Switch to HTTPS button. This restarts the service and switches the same port 9099 to HTTPS.
How it works
POS Application
│ HTTP POST (JSON)
▼
Nami Middleware ◄─── Windows Service on port 9099
│ Serial / TCP packet
▼
Nami Payment Terminal
The middleware handles all low-level terminal communication, so your POS only needs to send and receive JSON.
Two connection paths
| Path | When to use | How terminal connects to PC |
|---|---|---|
| TCP/IP | Terminal on same Wi-Fi or LAN as the PC | Network cable or Wi-Fi |
| COM (USB) | Terminal physically connected by USB cable | USB cable (auto-detects as COM port) |
Both paths use the same request/response format. Choose the one that matches your hardware setup.
Mandatory session sequence
Every communication session follows this order. Skipping steps causes errors.
1. Connect ─ Establish the link (TCP/IP: done inside /performTransactionTCPIP)
(COM: call /com/connect first)
2. REGISTER ─ Register your ECR with the terminal (required once per session)
3. Transact ─ PURCHASE, REFUND, RECONCILIATION, etc.
...repeat as needed...
4. Disconnect ─ Release the connection when done
REGISTER is mandatory
The REGISTER step must complete before any financial transaction. If you skip it, the terminal returns a "Registration Required" error.
Where to go next
- Deployment Topologies — one middleware per lane, or one central instance serving many TCP/IP terminals.
- Installation & First-Time Setup — install the service, the tray app, and optional HTTPS.
- Choose Your Testing Path — test from the dashboard or from Postman, against a real terminal or the built-in simulator.
- API Reference — every endpoint, field, and status code.
- Troubleshooting — symptoms, causes, and fixes.