API

This page is currently only available in English.

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 stored receipt bundle for the terminal. That may come from a transaction or from a terminal service operation.

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

Returns the most recent stored receipt bundles for the terminal across transaction and terminal service flows.

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/config

Triggers OPI ContactTMS and returns the parsed terminal configuration payload from the accept host ep2.

POST /terminals/:terminalAlias/init

Triggers OPI ContactAcq and returns the parsed merchant-contract initialisation and supported brand payload from the accept host ep2.

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 and performs the final balance with logoff at the end.

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
• /config and /init return parsed terminal service details, including status data and any supported brand data returned by the terminal
• service routes that print slips return receipt metadata and file paths, not the full receipt body
• 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 across the latest stored terminal receipts, including service-operation slips:

• 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": "..."
}