Integration and TCP Communication

This page is currently only available in English.

Looking for a simpler integration path?
The Nexi OPI Proxy turns raw TCP and XML terminal integration into a local HTTP and JSON API, while keeping the terminal-side OPI handling inside the proxy.
Explore the OPI Proxy

OPI is the low-level integration model for direct communication between a POS or ECR and a Nexi terminal. In this model, your checkout system talks directly to the terminal over TCP/IP and exchanges XML messages for payments, refunds, status requests, receipt handling, and device interactions.

This page gives the architectural picture first: what OPI is, what the POS is responsible for, what Nexi configures on the terminal side, and where the main integration boundaries are.

Quick Links

What OPI Means in Practice

At a high level, a direct OPI integration means:

your POS opens a TCP connection to the terminal
your POS sends XML requests in the OPI message format
the terminal answers with XML responses
the terminal may also call back into the POS for cashier display, receipt, journal, or input handling

That last part matters. OPI is not only "send amount, get result". It is a conversation between the POS and the terminal.

At a Glance

Transport: TCP/IP
Payload format: XML
Encoding: UTF-8
Framing: 4-byte message length prefix in network byte order
Main message families:
- CardServiceRequest / CardServiceResponse
- ServiceRequest / ServiceResponse
- DeviceRequest / DeviceResponse

TCP Connection and Message Framing

OPI rides on a normal TCP/IP connection, but the XML payload is not sent as a raw unframed stream.

Each message uses a 4-byte length prefix in network byte order, followed by the UTF-8 XML payload.

That means your POS needs to:

keep the socket open for the full exchange
read the length prefix first
then read the exact XML payload length
avoid assuming that one socket read always equals one full XML message

This is one of the reasons OPI integrations can feel more low-level than a typical REST API.

The Two-Channel Model

Direct OPI uses two logical communication directions:

Channel 0: POS to terminal for payment and service requests
Channel 1: terminal to POS for device interactions

A typical flow looks like this:

The POS sends a CardServiceRequest or ServiceRequest.
The terminal starts processing the request.
During the flow, the terminal may send one or more DeviceRequest messages back to the POS.
The POS must answer each one with a matching DeviceResponse.
The flow finishes with a CardServiceResponse or ServiceResponse.

This is the part many new integrations underestimate. If the POS does not handle DeviceRequest correctly, the overall integration is not complete even if the payment request itself is valid.

What Your POS Owns

In a direct OPI integration, your system is responsible for:

opening and managing the TCP connection
writing and reading framed XML messages
building valid OPI request XML
parsing OPI response XML
correlating request and response identifiers
handling DeviceRequest and replying with DeviceResponse
printing and storing receipts or journals where required
dealing with unknown-result recovery after communication problems
enforcing your own business rules such as refund permissions or transaction lookup

What Nexi and Terminal Parameters Own

Not everything is decided by the POS implementation alone. Some behaviour is configured on the terminal, host, or merchant setup.

Examples include:

which payment methods are enabled
whether DCC is enabled
whether tipping is enabled
receipt layout and receipt copies
login or logoff behaviour
submission behaviour
terminal software and parameter updates
whether specific request types are available on a given model

This is why an OPI integration should stay flexible. The XML message model is standardised, but not every terminal or merchant setup behaves the same way.

Network Model

For a local OPI setup, the POS and the terminal are typically on the same local network.

The POS usually needs to know:

the terminal IP address
the terminal port for payment and service traffic
the POS listener address and port for DeviceRequest

Recommended network approach:

keep the POS and terminal on a stable local network
prefer DHCP reservation or a static IP for the terminal
make sure local firewalls allow the configured OPI ports
make sure the terminal can reach the POS listener for device callbacks

Onboarding and Provisioning

Once a merchant is onboarded, terminal setup usually includes:

a TID
an activation code
remote parameter download if required

An internet connection is typically needed for:

first activation
parameter download
updates
normal host communication during transaction processing

The POS-to-terminal OPI communication itself is then local, using the terminal IP address.

The Main OPI Message Families

CardService

CardServiceRequest and CardServiceResponse cover card-related transaction flows such as:

payment
reservation / preauthorisation
refund
reversal
reprint

Service

ServiceRequest and ServiceResponse cover terminal-side service actions such as:

status
info
reconciliation
close day
transmit
login / logout
restart

Device

DeviceRequest and DeviceResponse handle terminal-driven interaction with the POS, for example:

cashier display output
receipt printer output
journal output
e-journal output
cashier keyboard input

What the POS Should Implement First

A robust OPI implementation does not need every optional field on day one. A strong first milestone is:

CardPayment
PaymentRefund
TicketReprint
GetInfo
GetStatus
Reconciliation
CloseDay
full DeviceRequest / DeviceResponse handling
receipt and journal handling
unknown-result recovery

That gives you a practical production baseline before you add more specialised flows.

If you do not want to build that full direct OPI baseline yourself, the Nexi OPI Proxy packages the same terminal-side model behind a smaller local HTTP API and a Docker-first runtime.

The Most Important Implementation Rules

Always keep identifiers clean

Use unique RequestID values and keep WorkstationID, RequestID, and RequestType consistent across the full flow.

Always answer `DeviceRequest`

Every DeviceRequest needs a matching DeviceResponse.

Treat receipt handling as part of the payment flow

Receipt and journal handling are not optional in practice. If the terminal cannot complete receipt handling, the next transaction may be blocked until the last receipt is reprinted or acknowledged properly.

Do not assume communication failure means payment failure

If the connection breaks, the transaction result may still be unknown. Recovery matters.

Only send fields that are valid for the selected message model

Do not add fields simply because they appear in receipt output or examples from another integration. Keep requests aligned with the actual OPI schema and the terminal profile in use.

Message Framing

Each XML payload is sent with a 4-byte length prefix:

[4-byte big-endian length][utf-8 xml payload]

Minimal Example

<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="1001"
                    RequestType="CardPayment"
                    ReferenceNumber="ORDER-1001"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2026-04-08T10:15:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
  <TotalAmount Currency="CHF">25.00</TotalAmount>
</CardServiceRequest>

When to Use the OPI Proxy Instead

If you want to avoid raw TCP, XML framing, DeviceRequest handling, and terminal-specific recovery logic in your POS, consider using the Nexi OPI Proxy instead.

The proxy turns the OPI integration into a simpler local HTTP API and keeps the OPI complexity inside the proxy service.