OPI Proxy

The Nexi OPI Proxy gives integrators a much cleaner way to work with Nexi terminals in Switzerland.

Instead of building a direct TCP and XML integration against OPI, you run one local Docker service and call a smaller HTTP and JSON API. The proxy keeps the OPI transport, XML message handling, terminal callbacks, and transaction follow-up logic inside the service.

Start using the Nexi OPI Proxy today!

Check out the Nexi OPI Proxy on GitHub, built to make terminal integrations over the OPI protocol much simpler and save you a lot of unnecessary headaches. 😉

richiehug/nexi-opi-proxy

Quick Links

Why Integrators Use the Proxy

Direct OPI is proven and powerful, but it pushes a lot of low-level responsibility into the POS:

• framed TCP messaging
• XML request construction
• XML response parsing
• DeviceRequest and DeviceResponse handling
• receipt and journal handling
• transaction reference storage for later capture, cancel, refund, and reprint

The proxy keeps that complexity out of the POS codebase and lets modern applications integrate over HTTP instead.

What the Proxy Abstracts

The proxy hides:

• TCP socket handling to the terminal
• OPI XML request generation
• OPI XML response parsing
• terminal callback handling during live flows
• receipt storage and transaction-linked receipt lookup
• stored transaction follow-up for capture, cancel, refund, and receipt retrieval

From the POS side, the model becomes:

• HTTP requests
• JSON payloads
• bearer tokens
• stable terminalAlias values
• stored transactionId based follow-up actions

Public Scope for 1.0.0

For the public 1.0.0 release, the official terminal scope is:

• Ingenico RX5000
• PAX Q30

That is the supported public scope for this release line.

What You Can Do Today

The current public proxy covers:

• health checks
• terminal info
• terminal status
• payment and preauthorisation
• terminal-side refund
• receipt reprint
• transmit
• close day
• activate and deactivate
• abort
• terminal reset
• stored transaction lookup
• capture, cancel, and refund by transactionId
• receipt lookup by transactionId
• latest and recent receipt lookup by terminalAlias

Runtime and Security Model

The public distribution is Docker-first.

That means:

• clone the public repo and run with Docker
• keep merchant-owned state in config/, data/, logs/, and certs/
• generate config/auth.json during initialization
• use HTTP on localhost for simple local setups
• use HTTPS by default for non-local traffic

The proxy supports bearer-token authentication with route-level scopes such as:

• terminals:read
• terminals:write
• transactions:read
• transactions:write
• receipts:read
• admin:manage

GET /health stays public for health checks.

What a First Payment Looks Like

One of the nicest things about the proxy is that a payment starts as a normal JSON request.

POST /terminals/front-counter/payment
Authorization: Bearer <token>
Content-Type: application/json

{
  "reference": "ORDER-1001",
  "amount": 49.90,
  "currency": "CHF",
  "paymentMethods": ["visa", "mastercard", "twint"]
}

The proxy then handles the OPI conversation with the terminal and returns a JSON response with a stored transactionId.

When the Proxy Is a Good Fit

The proxy is a strong fit when:

• your team prefers HTTP and JSON over raw TCP and XML
• you want OPI complexity out of the POS codebase
• you want to deploy with Docker instead of a custom Node runtime
• you want transaction-based follow-up actions such as capture or refund
• you want a local integration surface that is easier to support operationally