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
Open a socket to the terminal (port 7778 or 7777) and send the message wrapped in a SaleToPOIRequest envelope. Each message on the wire is preceded by a 4-byte big-endian length prefix giving the byte length of the JSON that follows, so the receiver knows where each message ends. The terminal streams messages back on the same connection — the intermediate DisplayRequest messages and the final response arrive as they occur. There is no polling and there are no HTTP status codes.
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.