Configuration

This page explains the runtime files that matter most when you deploy the public OPI Proxy bundle.

Quick Links

The Main Runtime Files

The public bundle uses one .env file plus a small set of JSON files in config/:

• .env
• config/terminal-models.json
• config/terminal-profiles.json
• config/terminals.json
• config/auth.json

The .env File

The most important .env settings are:

• HOST
• PUBLISHED_HOST
• PORT
• TLS_MODE
• TLS_CERT_FILE
• TLS_KEY_FILE
• LOG_LEVEL

Good starting points:

• local-only testing: PUBLISHED_HOST=127.0.0.1
• shared network access: PUBLISHED_HOST=0.0.0.0
• non-local access: TLS_MODE=required

Terminal Models, Profiles, and Terminals

The effective terminal config is merged in this order:

1. request values
2. terminal-specific values from terminals.json
3. profile values from terminal-profiles.json
4. model defaults from terminal-models.json
5. global defaults from .env

For public 1.0.0, the official supported terminal models are:

• Ingenico RX5000
• PAX Q30

Receipt Handling

The JSON API uses a cleaner receipt abstraction than raw OPI printer status fields.

Example:

{
  "receiptHandling": {
    "customer": "external",
    "merchant": "external"
  }
}

Allowed values:

• external
• local
• unavailable

The proxy maps that model to the required OPI printer status fields internally.

Payment Method Filtering

Requests can optionally include paymentMethods to restrict which brands are allowed for processing.

Example:

{
  "paymentMethods": ["visa", "mastercard", "twint"]
}

Important:

• this controls processing only
• it does not change which brands are shown on the terminal screen
• the terminal display is still determined by terminal configuration

Ownership Model

Treat the files like this:

• terminal-models.json: Nexi-owned release catalog data
• terminal-profiles.json: merchant or integrator owned after first setup
• terminals.json: merchant or integrator owned after first setup
• auth.json: generated locally and always environment owned