The Local API offers the same nexo 3.1 messages over two transports. The operations, fields, and results are identical — only the envelope, framing, and delivery differ. This article is the single reference for how messages are delivered; the operation guides link here. Choose one transport per integration.
At a glance
| HTTP | TCP/IP (socket) | |
|---|---|---|
| Message shape | Flat JSON (MessageHeader + body) |
Full SaleToPOIRequest / SaleToPOIResponse envelope |
| Framing | Standard HTTP request/response | 4-byte big-endian length prefix before each JSON message |
| Delivery |
POST returns 202, then GET-poll for messages |
Messages stream back on the open socket |
| Default port | 8080 |
7778 (Master App / integrated) or 7777 (standalone / mixed) |
HTTP: flat JSON, poll for the result
Send the flat message to http://<terminal-ip>:8080/<resource>, where <resource> is named after the operation (/payment, /reversal, …; see the reference on MuleSoft). Asynchronous operations return 202 Accepted; you then GET the same resource until a final result. Each poll returns one of:
| Status | Meaning | POS action |
|---|---|---|
200 OK |
Final message — the operation's response (or an EventNotification) |
Read the result; the exchange is complete |
201 Continue |
Intermediate DisplayRequest; nothing more pending right now |
Render the cashier display; keep polling |
204 No Content |
No message available yet | Wait briefly, then poll again |
206 Partial Content |
More display messages are queued | Render the display; poll again immediately |
423 Locked |
No active operation on this endpoint | Stop polling |
A POST returns 403 if a transaction is already in progress on that endpoint.
Note
Only 200 closes the exchange. Never treat 201 or 206 as final — they carry the cashier-display prompts shown to the shopper during the transaction.
TCP/IP: envelope with a length prefix
The same Nexo messages over a persistent TCP socket, default port 7778 (configurable via terminal configuration). Differences from HTTP:
-
Envelope: each message is wrapped in
SaleToPOIRequest/SaleToPOIResponse. - Framing: each frame is a 4-byte big-endian length prefix followed by the UTF-8 JSON payload.
- Delivery: no polling — responses (and intermediate display notifications) are streamed on the open socket as they occur.
Choose the socket when you need a persistent, low-latency connection and can manage framing yourself; choose HTTP for the simplest, most portable build.
Warning
The length prefix is mandatory on the socket transport. Sending raw JSON with no prefix, or a wrong length, leaves the terminal waiting for bytes that never arrive, and the connection appears to hang.
Which operations are asynchronous
The delivery pattern above (HTTP polling / TCP streaming with intermediate DisplayRequest messages) applies to the asynchronous operations:
- Payment, Reversal, Card Acquisition, Reconciliation, Activation, Application Update, Balance Inquiry, and Gift Card.
Login, Logout, Abort, and TransactionStatus are synchronous — a single request and its response.
Note
Both transports share one contract — see the full schema and the HTTP resource list on the Local API reference on MuleSoft. The HTTP Postman collection is attached to the Quickstart and API reference articles.
Related
- Quickstart: the pattern in action with curl.
- Troubleshooting: polling never returns 200 and Timeout failures: the two transport failure modes.