Terminal API architecture

VINR terminals operate in two connectivity modes: Cloud mode, where your backend drives the terminal through the VINR API, and Local mode, where your POS application talks directly to the terminal over your local network. Both modes produce identical payment objects, emit the same webhooks, and support the same card entry methods — the difference is entirely in how instructions reach the device.

Cloud modeAskCopy

In Cloud mode your server never communicates with the terminal directly. You POST a payment intent to the VINR API and VINR's cloud infrastructure pushes the collect action to the terminal in real time.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payment = await vinr.terminal.payments.create({
  amount: 2500,
  currency: 'EUR',
  terminalId: 'term_7Kx9mBq',
  description: 'Table 12 — dinner',
});

Advantages

• No LAN access needed between your server and the terminal — works across the public internet.
• Centralized control: cancel or redirect any terminal from your dashboard or API.
• Simple integration: one POST from any backend language, no SDK required on the POS device.

Trade-offs

• Requires continuous internet connectivity on both sides.
• Round-trip latency adds ~200–400 ms before the terminal screen activates.

Local modeAskCopy

In Local mode your POS application discovers the terminal on the same local network and sends payment commands directly to the device's HTTPS endpoint. VINR's cloud is only involved for the card authorization; it is not in the command path.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const reader = await vinr.terminal.readers.discover({ network: 'local' });

const payment = await vinr.terminal.payments.createLocal({
  readerId: reader[0].id,
  amount: 1800,
  currency: 'EUR',
  description: 'Counter sale #0091',
});

Advantages

• Lowest latency: the activate-screen round trip is sub-50 ms on a local network.
• Resilient to intermittent internet outages — supported models can queue and defer authorization.
• Suitable for high-throughput counters and kiosk environments.

Trade-offs

• Your POS device must be on the same LAN (or VLAN) as the terminal, or you must manage static IP routes.
• Discovery and certificate provisioning add integration complexity.

Choosing a modeAskCopy

Connectivity requirementsAskCopy

Each supported device exposes a different set of radios. Choose hardware that matches your network infrastructure.

All five devices support contactless (NFC), chip+PIN, and magnetic stripe regardless of connectivity mode.

SecurityAskCopy

• All traffic between your server and the VINR API uses TLS 1.2 or higher. Legacy cipher suites (RC4, 3DES) are rejected at the gateway.
• All traffic between your POS and a terminal in Local mode uses TLS 1.2 or higher with mutual TLS: the terminal presents a VINR-issued per-device certificate and your POS validates it against a pinned CA bundle included in the SDK.
• Your API secret key never touches the terminal. Terminals are provisioned with a separate device credential that cannot be used to call the VINR API directly. If a terminal is lost or stolen, revoke its device certificate from the dashboard without rotating your API key.
• Webhook payloads are signed with an HMAC-SHA256 signature under X-VINR-Signature. Always verify the signature before acting on the event — see Webhooks.

Next stepsAskCopy