Local API

In Local API mode your POS application communicates directly with the terminal over your local network. VINR's cloud handles card authorization but is not in the command path — the terminal screen activates in under 50 ms. Supported devices can also queue and defer authorization when internet connectivity drops.

Choose Local API when:

• You need the fastest possible screen activation — fixed-lane retail, high-throughput counters, kiosks
• Your environment has unreliable internet and you need offline payment queuing
• You are building a custom POS application on hardware that shares a LAN with the terminal

For server-side or cloud-hosted POS systems, see Cloud API. To connect an existing ECR or third-party POS system without writing custom code, see ECR Integration.

How it worksAskCopy

Your POS app ──HTTPS──▶ Terminal (LAN, port 8443)
                               │
                         Card interaction
                               │
                         ──▶ Card network (authorization via internet)
                               │
Your POS app ◀─────────── Terminal (synchronous response)
                               │
                        VINR cloud ──▶ webhook → Your server

1. Your POS discovers the terminal on the local network and authenticates with a per-device client certificate.
2. Your POS sends the payment command directly to the terminal's HTTPS endpoint on port 8443. VINR's cloud is not involved at this stage.
3. The terminal handles the card interaction and routes authorization to the card network. If internet is unavailable, it can queue the transaction for deferred authorization (device-dependent).
4. The terminal returns the outcome synchronously. VINR's cloud also fires a webhook to your server after the authorization settles.

PrerequisitesAskCopy

• Your POS device and the terminal must be on the same LAN or VLAN, or connected via a static route.
• Port 8443 must be open inbound on the terminal's IP address from your POS device.
• Local mode enabled on the terminal: Dashboard → Hardware → Terminals → [device] → Connectivity → Enable Local mode.
• A per-device client certificate provisioned from the Dashboard (see Security below).

Terminal discoveryAskCopy

mDNS (automatic)

Each VINR terminal advertises _vinr-terminal._tcp.local via mDNS. The SDK resolves this automatically on flat networks.

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

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

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

console.log(readers);
// [{ id: 'term_CT20_0042', ip: '192.168.1.51', model: 'nexgo_ct20', status: 'online' }]

Static IP (enterprise networks)

Enterprise networks commonly block mDNS across VLANs. Use DHCP reservations at your router and pass static host addresses to bypass discovery:

const readers = await vinr.terminal.readers.discover({
  network: 'local',
  staticHosts: ['192.168.10.51', '192.168.10.52', '192.168.10.53'],
});

Static hosts connect directly over port 8443 without mDNS. Combine with DHCP reservations so IP addresses remain stable across device reboots.

SecurityAskCopy

All Local API traffic uses mutual TLS (mTLS):

• The terminal presents a VINR-issued per-device certificate. Your POS validates it against the VINR terminal CA bundle, which is bundled with the SDK.
• Your POS presents a client certificate provisioned from the Dashboard. The terminal rejects any request without a valid, matching client certificate.
• Your API secret key never reaches the terminal. Terminals carry a separate device credential. Revoking a lost device from the Dashboard does not require rotating your API key.

Provision a client certificate

const vinr = new Vinr({
  secretKey: process.env.VINR_SECRET_KEY,
  terminal: {
    localCertPath: '/etc/vinr/client.p12',
    localCertPassphrase: process.env.VINR_LOCAL_CERT_PASSPHRASE,
  },
});

Create a paymentAskCopy

const payment = await vinr.terminal.payments.createLocal({
  readerId: 'term_CT20_0042',
  amount: 2500,
  currency: 'USD',
  reference: 'order_8821',
});

// Response is synchronous — the SDK holds the connection until card interaction completes
console.log(payment.status); // 'completed' or 'failed'
console.log(payment.last4, payment.brand);

The response object is identical in shape to a Cloud API payment. Both completed and failed results are returned synchronously — no need to poll or wait for a webhook for the initial outcome.

Without the SDK (direct HTTP)AskCopy

If you cannot use the VINR SDK, send a POST request directly to the terminal's HTTPS endpoint. You are responsible for mTLS and certificate pinning.

POST https://{terminal-ip}:8443/v1/pay
Content-Type: application/json

{
  "terminalId": "term_CT20_0042",
  "amount": 2500,
  "currency": "USD",
  "reference": "order_8821",
  "captureMethod": "automatic"
}

Download the VINR terminal CA bundle from Dashboard → Developers → Certificates and configure it as the trusted root in your HTTP client. Your .p12 client certificate must be loaded as the client identity on every request.

Timeout recoveryAskCopy

If your connection times out before receiving a response, do not immediately create a new payment. The terminal may have completed the transaction even though your client closed the connection.

const payment = await vinr.terminal.payments.retrieveByReference('order_8821');

Offline paymentsAskCopy

When the terminal temporarily loses internet connectivity, supported devices queue transactions and submit them for authorization when connectivity resumes.

Offline transactions are stored encrypted on the device. On reconnection the terminal submits the queued authorizations and VINR fires terminal_payment.completed webhooks for each. If an offline authorization is declined post-reconnect, VINR fires terminal_payment.failed with declineCode: 'offline_auth_declined'.

Hybrid modeAskCopy

Hybrid mode uses Local API as the primary path and falls back to Cloud API automatically when the LAN path is unavailable. Recommended when terminals and POS devices share a reliable LAN but cloud fallback is needed for resilience.

const payment = await vinr.terminal.payments.create({
  terminalId: 'term_CT20_0042',
  amount: 2500,
  currency: 'USD',
  reference: 'order_8821',
  connectivity: {
    mode: 'hybrid',
    localTimeoutMs: 2000,
  },
});

// which path was used
console.log(payment.metadata.connectionMode); // 'local' or 'cloud'

If the local call does not respond within localTimeoutMs, the SDK re-issues the command via VINR cloud. The payment.metadata.connectionMode field records which path was used — monitor this in your logs to detect degraded LAN conditions before they become customer-facing issues.

Multi-terminal routingAskCopy

For high-throughput counters with multiple terminals, pass a group of terminal IDs. VINR selects the first idle terminal; if all are busy, it queues and resolves to whichever becomes free first.

const payment = await vinr.terminal.payments.create({
  amount: 1500,
  currency: 'USD',
  reference: 'order_8822',
  terminalGroup: ['term_CT20_0042', 'term_CT20_0043', 'term_CT20_0044'],
});

console.log(payment.terminalId); // ID of the terminal that handled it

TestingAskCopy

The VINR SDK includes a local simulator that runs on your development machine, behaving identically to a physical terminal on the LAN.

const vinr = new Vinr({
  secretKey: 'sk_test_...',
  terminal: { localSimulator: true },
});

const readers = await vinr.terminal.readers.discover({ network: 'local' });
// [{ id: 'term_local_simulator', ip: '127.0.0.1', model: 'simulator' }]

const payment = await vinr.terminal.payments.createLocal({
  readerId: 'term_local_simulator',
  amount: 1000,
  currency: 'USD',
  reference: 'local_test_001',
});

The simulator supports all test card numbers from the Cloud API. Pass simulateOffline: true in the options to test offline queuing behaviour without disconnecting any hardware.

Next stepsAskCopy