API

The proxy API is intentionally smaller and easier to consume than raw OPI. You send JSON requests to the proxy, and the proxy handles the terminal-side OPI conversation.

Quick Links

API Basics

terminal-scoped operations use terminalAlias
stored follow-up actions use transactionId
almost all routes require a bearer token
GET /health is intentionally public

Authentication

Use:

Authorization: Bearer <token>

Health

`GET /health`

Example response:

{
  "ok": true,
  "service": "nexi-opi-proxy",
  "version": "1.0.0"
}

Terminal Routes

`GET /terminals/:terminalAlias/info`

Returns terminal information, parsed info-receipt data, and discovered payment methods when available.

`GET /terminals/:terminalAlias/status`

Returns terminal status and cached reachability information.

`GET /terminals/:terminalAlias/receipts/latest`

Returns the latest receipt-producing transaction for the terminal.

`GET /terminals/:terminalAlias/receipts?limit=5`

Returns the most recent receipt-producing transactions for the terminal.

`POST /terminals/:terminalAlias/payment`

Starts a sale or a preauthorisation.

`POST /terminals/:terminalAlias/refund`

Starts a direct terminal-side refund.

`POST /terminals/:terminalAlias/reprint`

Requests a reprint of the last receipt through the terminal.

`POST /terminals/:terminalAlias/transmit`

Triggers OPI TransmitTrx.

`POST /terminals/:terminalAlias/activate`

Activates or logs in the terminal when the target setup requires it.

`POST /terminals/:terminalAlias/deactivate`

Deactivates or logs out the terminal when the target setup requires it.

`POST /terminals/:terminalAlias/abort`

Sends an abort request for an in-progress card flow.

`POST /terminals/:terminalAlias/close`

Triggers OPI CloseDay.

`POST /terminals/:terminalAlias/reset`

Requests a terminal restart.

Payment Example

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

{
  "reference": "ORDER-100045",
  "amount": 24.90,
  "currency": "CHF",
  "paymentMethods": ["visa", "mastercard", "twint"],
  "receiptHandling": {
    "customer": "external",
    "merchant": "external"
  }
}

Important notes:

autoCapture=true means sale
autoCapture=false means preauthorisation
ClerkId and ShiftNumber are optional and are omitted from OPI if not supplied
paymentMethods limits which brands can be processed, not which brands the terminal UI shows
tips and DCC are terminal-side configuration topics, not public JSON request flags

Receipt Routes

The canonical receipt lookup is transaction-based:

`GET /transactions/:transactionId/receipts`

That is the stable route to use once you have a stored transactionId.

The terminal receipt routes are convenience lookups:

GET /terminals/:terminalAlias/receipts/latest
GET /terminals/:terminalAlias/receipts?limit=5

Transaction Routes

`GET /transactions/:transactionId`

Reads a stored transaction.

`POST /transactions/:transactionId/capture`

Captures a stored preauthorisation.

Example:

{
  "amount": 120.00
}

`POST /transactions/:transactionId/cancel`

Cancels a stored preauthorisation.

`POST /transactions/:transactionId/refund`

Refunds a stored sale or captured transaction.

Example:

{
  "amount": 25.00
}

`PATCH /transactions/:transactionId`

Admin-only recovery route for manual transaction correction.

Response Style

Successful responses return JSON data plus requestId.

Error responses use this shape:

{
  "error": {
    "code": "SOME_CODE",
    "message": "Human-readable message"
  },
  "requestId": "..."
}