Integrate your ECR · task 4 of 8

You'll need AIC running with your test terminal connected to it.

Your ECR sends messages to AIC as JSON, and AIC passes them to the terminal. The messages follow the European standard Nexo Retailer 3.1, with some Aera additions. The message content is the same for Local integration and Cloud integration. How you connect, keep the connection alive and find terminals is different.

Using cloud integration? Your ECR backend sends messages over the internet (REST over HTTPS) instead of WebSocket. Connect as described in Cloud integration, then continue with Cloud integration: find the terminal ID below.

Connect to AIC

Your ECR opens a WebSocket connection to AIC on port 8002:

ws://<AIC host>:8002/ws/nexo?saleName=<your ECR ID>

Example, with AIC on the same computer as the ECR:

ws://localhost:8002/ws/nexo?saleName=ECR1

• saleName is the ID of your ECR. Use the same value as SaleID in every message.
• Send each message as one WebSocket text frame, in UTF-8.
• Keep the address in your ECR's settings, not in code, so installers can change it.
• AIC tells you its version in the HTTP response header Aera-AIC-Version. Log it for troubleshooting.

Find the terminal ID

Local integration

If your ECR doesn't already know which terminal to use, ask AIC:

GET http://<AIC host>:8002/poi-list

The response lists each terminal with its ID (poiName) and its connectionStatus:

[
  { "poiName": "AT12345", "connectionStatus": "Disconnected" },
  { "poiName": "AT54321", "connectionStatus": "Connected" }
]

• Connected: the terminal is connected to AIC and ready for messages.
• Disconnected: the terminal has been connected since AIC started, but isn't connected now.
• An empty list ([]) means no terminal is connected to AIC.

Use the poiName of a Connected terminal as POIID in your messages. If there is none yet, wait a moment and ask again until a terminal shows Connected. Keep this address in your ECR's settings too.

Cloud integration

Ask AIC which terminals you can use (a synchronous request):

GET https://<cloud AIC host>/poi-list

Keep this address in your ECR's settings, not in code.

The response lists your terminals:

Only one ECR can be logged in to a terminal at a time.

Keep the connection alive

With local integration:

• Your ECR and AIC both send a keep-alive every 5 seconds. A keep-alive is an empty text frame.
• Your ECR must have a read timeout of 10 seconds: if nothing arrives for 10 seconds, close the connection and open it again. If a payment was in progress, check TransactionStatus before you try again.

While you develop, you can turn this off: set EcrKeepAlive to false in appsettings.json. Turn it back on for production. See Prepare your release.

How a message looks

• Every message is wrapped in SaleToPOIRequest (a request) or SaleToPOIResponse (a response). "Sale" is your ECR and "POI" is the terminal. The names stay the same whichever way the message travels.
• Every message starts with a message header. See Message header.
• Fields that Aera has added to Nexo start with Ae, for example AeResponseCode.

To see a complete message, open Login or Payment. Every field and full example messages are in Terminal API.

Which IDs to use

Three kinds of messages

Open a session

1. Connect to AIC. See Connect to AIC (local integration) or Cloud integration.
2. Send Login. The response tells you which card brands the terminal accepts, and gives its software version and serial number. Log these for troubleshooting.
3. Send your transactions, for example a Payment.
4. Send Logout when the ECR closes.

• Log in again when you get LoggedOut. The terminal is connected but lost its session, for example after a restart. Send Login, then repeat the request.
• One ECR per terminal. Only one ECR can be logged in to a terminal at a time.

Take your first payment

Put it all together in code: connect, log in, take a payment and read the result.