Guides

Testing via Postman

Import the ready-made collection, set a few variables, and run requests in order — including a full simulator flow with no physical terminal.

Suggest Edits

A ready-to-import Postman collection ships with the middleware. It's the fastest way to integrate from outside a browser — every request is pre-built with the correct headers, body shape, and inline documentation.

Importing the collection

  1. In Postman, click Import → File → select Nami Middleware API 1.7.postman_collection.json.
  2. Open the collection's Variables tab and review/edit these collection-level variables:
VariableDefaultNotes
baseUrlhttp://localhost:9099Change only if the middleware runs on a different host/port
terminalIp192.168.1.100Set to your real terminal's IP for PATH B (TCP/IP) — or to localhost/127.0.0.1 when testing against the Simulator
terminalPort8888Real terminal port, or the Simulator's listening port (default 8888)
comPort10Numeric COM port (e.g. 10 for COM10) — get this from "Step 1 — Discover COM Ports"
ecrRef0000000000000114-digit ECR reference number — must be unique per transaction; increment between requests

📘

The date field is generated for you

Most requests use a pre-request script to auto-generate the date field — you don't need to set it manually.

Collection folders

FolderContents
🔎 Service StatusHealth check, registration status, cancel active transaction, list existing TCP connections
🔌 [PATH A] USB COM PortDiscover COM ports → Connect → Register → Purchase/Refund/Reversal/Reconciliation/Duplicate/Check Status → Disconnect
📡 [PATH B] TCP/IP NetworkRegister → Purchase/Refund/Reversal/Reconciliation/Duplicate/Check Status → Disconnect (connection is automatic — no separate connect step)
🧪 [PATH C] Simulator (No Physical Terminal)Start Simulator → Check Status → Simulate Card Tap → Stop Simulator — see below
⚙️ Configuration & AdminGet/update CORS allowed origins, clear terminal data cache, get cached terminal responses
📋 Diagnostics & LogsRecent logs, export current log, list/download log files

Using Postman with the Simulator

This is the quickest way for a third-party integrator to validate their request/response handling without a physical terminal or even opening the dashboard. Everything below runs from the 🧪 [PATH C] Simulator folder, driving the same TCP Simulator described in Using the built-in Simulator.

Step 1 — Start Simulator

POST {{baseUrl}}/api/simulator/start?port={{terminalPort}}

Starts the simulator listening on terminalPort (default 8888). Response:

{ "success": true, "message": "Simulator server started on port 8888", "port": 8888 }

Step 2 — Send transactions through PATH B

Set the collection variable terminalIp to localhost (or 127.0.0.1) and terminalPort to the port you started the simulator on, then run PATH B [TCP/IP Network] requests normally — REGISTER first, then any transaction type. The simulator supports all transaction types (REGISTER, PURCHASE, REFUND, REVERSAL, RECONCILIATION, DUPLICATE, CHECK_STATUS, and more).

Step 3 — Check Simulator Status

GET {{baseUrl}}/api/simulator/status

{
  "running": true,
  "port": 8888,
  "connectionsHandled": 3,
  "currentScreenState": "waiting_card",
  "pendingCardAction": true
}

For card-type transactions (Purchase, Refund, UPI, Authorization, Cash Advance), the PATH B request you sent in Step 2 will block until you resolve the card action in Step 4 — pendingCardAction: true tells you it's waiting. Non-card transactions (Reconciliation, Reversal, etc.) respond immediately without this step.

currentScreenState values: idle, online, waiting_card, approved, declined, receipt, reg_ok, recon_ok.

Step 4 — Simulate Card Tap

POST {{baseUrl}}/api/simulator/card-action?action=approve

actionEffect
approveRC 000 — APPROVED
timeoutRC 993 — ECR CONNECT TIME OUT
declineRC from reason query param, e.g. &reason=116 for INSUFFICIENT FUNDS

Decline codes: 100 Do Not Honour, 116 Insufficient Funds, 101 Expired Card, 117 Incorrect PIN, 121 Exceeded Daily Limit, 102 Suspected Fraud, 998 Blocked Card, 987 User Cancelled.

As soon as this call completes, the PATH B request from Step 2 receives its final response — Postman shows it in that request's response panel, not this one.

Step 5 — Stop Simulator

POST {{baseUrl}}/api/simulator/stop

{ "success": true, "message": "Simulator server stopped" }

📘

Working across two open requests

Steps 2 and 4 happen on two different open requests in Postman — send the transaction request in Step 2, switch tabs to send Step 4's card action while it's pending, then switch back to see the completed response on the Step 2 tab.