The Local API follows the nexo Sale-to-POI protocol, version 3.1. Every exchange is a pair of JSON messages — a request from your POS and a response from the terminal — and every message has the same two-part shape.
Request and response structure
A request carries a MessageHeader and one operation body named after the operation, for example a PaymentRequest or a LoginRequest:
{
"MessageHeader": { ... },
"PaymentRequest": { ... }
}The response echoes the header — with MessageType set to Response — and returns the matching body, for example a PaymentResponse carrying a Response object with a Result of Success, Failure, or Partial.
Note
Over HTTP, messages are sent flat, exactly as shown. Over the TCP/IP socket the same messages are wrapped in a SaleToPOIRequest / SaleToPOIResponse envelope. See Transport bindings: TCP/IP vs HTTP.
The MessageHeader
The header identifies the operation and routes the message. Its fields:
| Field | Purpose |
|---|---|
ProtocolVersion |
Always 3.1 for this API |
MessageClass |
Service for transactions, Device / Event for display and notifications |
MessageCategory |
The operation: Login, Payment, Reversal, Abort, TransactionStatus, Admin, … |
MessageType |
Request or Response
|
ServiceID |
Unique identifier of the message pair — the basis of duplicate detection |
SaleID |
Identifies your POS system / lane |
POIID |
Identifies the terminal |
The identifiers you must get right
Three identifiers cause most integration incidents. Treat them as first-class values in your POS, not afterthoughts:
| Identifier | Rule |
|---|---|
ServiceID |
Unique per message pair within a session (max 10 characters). A reused or constant value defeats duplicate-payment protection. |
TransactionID |
Your sale reference inside SaleTransactionID. 35 characters maximum — longer values are rejected with response code 90001. |
POITransactionID |
Returned by the terminal in the payment response. Persist it — reversals, refunds, and status queries all reference it. |
Warning
A raw UUID is 36 characters and will silently fail as TransactionID (90001). Use a shorter ticket reference, or truncate deterministically to 35 characters.
Note
See the Local API reference on MuleSoft for the full schema of every message and body.