OPI Protocol

OPI stands for Open Payment Interface Protocol. At Nexi Switzerland, it is the classic low-level way to communicate with integrated and semi-integrated payment terminals.

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

If you implement OPI directly, your POS or ECR opens a TCP connection to the terminal, exchanges XML messages, and handles terminal-driven callbacks such as receipts, display output, and input requests.

Quick Links

What the OPI Protocol Is

The Open Payment Interface Protocol is the terminal-facing integration layer used by many traditional POS and ECR solutions. It gives the cash register system a structured way to talk directly to the terminal for payment and service operations.

In practice, that means:

• TCP/IP transport between POS and terminal
• XML messages for requests and responses
• terminal-driven callback messages for display, printing, input, and journal handling
• a local-network operating model for most merchant setups

OPI is powerful because it maps closely to the terminal's real behaviour. It is also demanding because the POS becomes responsible for more than a single request-response call.

Why Integrators Still Use Direct OPI

Direct OPI still makes sense when a POS team wants full control over the terminal conversation and is comfortable working close to the transport layer. Typical reasons include:

• existing POS platforms already built around OPI
• strict ownership of terminal-side flow logic inside the POS
• a need to work with raw terminal responses and references
• environments where direct terminal integration is already the established model

For teams with that profile, OPI remains a solid and proven integration option.

What a Direct OPI Integration Really Means

Direct OPI gives integrators fine-grained control, but it also means your application owns the terminal conversation end to end. That includes:

• TCP socket handling
• XML request construction
• XML response parsing
• DeviceRequest and DeviceResponse callbacks
• receipt and journal handling
• transaction recovery after communication issues

For some teams that is exactly the right fit. For others, it is more practical to keep this complexity in the Nexi OPI Proxy and integrate over HTTP instead.

How OPI Communication Works

An OPI conversation is more interactive than many first-time integrators expect. The POS does not simply send a payment request and wait in silence for a final answer. During a live transaction, the terminal can send callback messages back to the POS for:

• receipt handling
• cashier display output
• keyboard or cashier input
• journal or e-journal output

That is why a production-ready OPI integration usually needs:

• a stable local network
• a POS listener for device callbacks
• a clean request and response correlation model
• good logging and recovery behaviour

Most TCP/IP OPI installations use one terminal-facing request port and one POS-facing callback port. Common defaults are TCP 4100 from the POS to the terminal for payment and service requests, and TCP 4102 from the terminal back to the POS for DeviceRequest callbacks. Both directions must be reachable. If only the POS-to-terminal path works, a transaction can begin but still get stuck when the terminal needs receipt, display, journal, input, or delivery acknowledgement handling.

Unattended Terminals

Unattended OPI is an add-on to the normal attended model, not the baseline. In Swiss self-service setups, terminals are usually integrated either directly over OPI with a dedicated controller or through MDB, so most teams only need this topic when the terminal profile explicitly requires DeliveryBox. DeliveryBox is the extra terminal callback used to confirm whether the product or service was really delivered after authorisation.

If that applies to your setup, your controller must be able to:

• receive a DeviceRequest for OutDeviceTarget="DeliveryBox"
• trigger delivery at the correct point in the flow
• return Success only after real delivery
• return Failure when delivery did not happen
• use Busy only if the target profile supports it
• keep payment and delivery evidence linked for later support

The full unattended flow, XML examples, and recovery guidance are documented on Unattended Terminals.

Important Things to Understand Early

Before building the first payment flow, it helps to get these points clear:

• OPI is transport-aware, not just message-aware
• callbacks are part of the protocol, not an optional extra
• payment recovery matters as much as the happy path
• terminal configuration can change behaviour without changing your XML
• receipts and journals are part of the operational flow

Teams that absorb these points early usually move faster once certification-style testing begins.

OPI Proxy

The Nexi OPI Proxy exists for teams that want the terminal capabilities of OPI without pushing raw TCP and XML responsibilities into their POS codebase.

Instead of implementing the full OPI transport contract yourself, you can:

• call a local HTTP API
• send JSON payloads
• let the proxy manage OPI framing, callbacks, parsing, and stored transaction follow-up logic