Viva Local Terminal TypeScript SDK

⚠️ Ce n'est PAS l'API cloud Viva This is NOT the Viva cloud API

Spec officielle : « In a closed network environment, authentication is not required for peer-to-peer communication. [...] eliminating the need to include an Authorization tag in the header. »

Modèle asynchrone (polling)

Les opérations de transaction (sale, refund, capturePreauth…) résolvent immédiatement un state (typiquement PROCESSING) et un sessionId. Vous générez vous-même le sessionId (UUID), puis vous interrogez terminal.sessions.get(sessionId) jusqu'à SUCCESS ou FAILURE (champ payloadData renseigné).

Prérequis réseau

1. L'hôte exécutant votre code et le terminal doivent être sur le même LAN.
2. Vous devez connaître l'IP et le port du terminal (app Viva.com Terminal, réseau, ou zeroconf/mDNS).
3. Le terminal sert du HTTPS, généralement avec un certificat auto-signé — voir TLS.

Installation

Installez le SDK via npm / pnpm. Requiert Node 18+ (ou tout runtime avec fetch global : navigateurs, Deno).

Install via npm / pnpm. Requires Node 18+ (or any runtime with a global fetch).

npm install @qrcommunication/viva-local-terminal-sdk
# ou
pnpm add @qrcommunication/viva-local-terminal-sdk

Publié en ESM + CJS avec types .d.ts.

Démarrage rapide Quick Start

import { VivaLocalTerminalClient } from "@qrcommunication/viva-local-terminal-sdk";
import { randomUUID } from "node:crypto";

// 1. Pointer le client sur l'IP + port du terminal sur le LAN
const terminal = new VivaLocalTerminalClient({
  terminalBaseUrl: "https://192.168.1.50:8080", // IP + port du terminal
  verifyTls: false,                              // certificat auto-signé sur LAN fermé
});

// 2. Démarrer une vente (montant en centimes) — vous générez le sessionId
const sessionId = randomUUID();
const res = await terminal.transactions.sale({
  sessionId,
  amount: 1170,        // 11,70 EUR
  currencyCode: 978,   // EUR
  merchantReference: "order-123",
});
// res.state === "PROCESSING"

// 3. Interroger le résultat une fois le client ayant payé
const session = await terminal.sessions.get(sessionId);
// session.state === "SUCCESS" une fois la carte traitée

// 4. Contrôler le terminal
await terminal.device.screenControl(true);
await terminal.device.brightness(0.5);

Configuration

Le constructeur reçoit un objet d'options et n'accepte aucun identifiant (pas de clé API, client ID ou secret) — le modèle P2P est sans authentification.

The constructor takes an options object and accepts no credentials — the P2P model is unauthenticated.

Propriétés publiques

terminal.transactions  // Transactions
terminal.sessions      // Sessions
terminal.device        // Device

terminal.getConfig();  // Config courante (introspection)

TLS — certificats auto-signés TLS — self-signed certificates

Le terminal sert du HTTPS, le plus souvent avec un certificat auto-signé.

// 1. Vérification standard (CA système) — défaut. Échoue sur cert auto-signé.
const terminal = new VivaLocalTerminalClient({
  terminalBaseUrl: "https://192.168.1.50:8080",
});

// 2. Désactiver la vérification (modèle de confiance LAN-only)
// Sur Node, un Agent undici avec rejectUnauthorized: false est attaché automatiquement.
const terminal = new VivaLocalTerminalClient({
  terminalBaseUrl: "https://192.168.1.50:8080",
  verifyTls: false,
});

// 3. Contrôle fin : fournir votre propre Dispatcher undici (ex : CA pinné)
import { Agent } from "undici";
const terminal = new VivaLocalTerminalClient({
  terminalBaseUrl: "https://192.168.1.50:8080",
  dispatcher: new Agent({ connect: { ca: myTerminalCaPem } }),
});

Ressources

const res = await terminal.transactions.sale({
  sessionId: "4bdebe62-c211-4ca0-a994-b2fbea2061c5",
  amount: 1170,          // 11,70 EUR
  currencyCode: 978,     // EUR
  merchantReference: "order-123",
  showReceipt: true,
});

console.log(res.state);       // "PROCESSING"
console.log(res.sessionType); // "SALE"

// Puis polling :
const session = await terminal.sessions.get(res.sessionId!);

const res = await terminal.transactions.capturePreauth({
  sessionId: crypto.randomUUID(),
  amount: 1500,          // 15,00 EUR
  transactionId: "preauth-transaction-id",
});

const res = await terminal.transactions.refund({
  sessionId: crypto.randomUUID(),
  amount: 1170,
  transactionId: "original-sale-transaction-id",
});

const res = await terminal.transactions.unreferencedRefund({
  sessionId: crypto.randomUUID(),
  amount: 500, // 5,00 EUR
});

await terminal.transactions.abort("4bdebe62-c211-4ca0-a994-b2fbea2061c5");

const res = await terminal.transactions.aadeFimControl(
  "ECR0210U/RCFB77000041/CMAC_K:1ED9F7AE0B2509281BBC2DE38EF2A12B:CC5FFF",
);
console.log(res.status);  // "success"
console.log(res.message); // "Fim control success"

import { TransactionTypeId } from "@qrcommunication/viva-local-terminal-sdk";

const result = await terminal.transactions.retrieve({
  transactionTypes: [TransactionTypeId.SALE, TransactionTypeId.REFUND],
  startDate: "2026-03-01T00:00:00Z",
  endDate: "2026-03-31T23:59:59Z",
});

for (const txn of result.transactions ?? []) {
  console.log(txn.orderCode);
}

import { SessionState } from "@qrcommunication/viva-local-terminal-sdk";

async function pollSession(terminal, sessionId) {
  for (;;) {
    const session = await terminal.sessions.get(sessionId);

    if (session.state === SessionState.SUCCESS) {
      return session; // session.payloadData contient le détail
    }
    if (session.state === SessionState.FAILURE) {
      throw new Error("Paiement échoué");
    }

    await new Promise((r) => setTimeout(r, 2000)); // attendre 2 s
  }
}

const res = await terminal.device.screenControl(true);
console.log(res.isSuccess); // true

await terminal.device.brightness(0.5); // 50 %
await terminal.device.brightness(1.0); // maximum
// await terminal.device.brightness(0); // ❌ RangeError

Enums

Exportés depuis le point d'entrée du package.

SessionState

SessionType

TransactionTypeId

PaymentMethod

Gestion des erreurs Error Handling

Error
└── VivaError     (base de toute erreur SDK)
    └── ApiError  (levée sur 4xx/5xx ET sur terminal injoignable : httpStatus === 0)

import { ApiError } from "@qrcommunication/viva-local-terminal-sdk";

try {
  const res = await terminal.transactions.sale({ sessionId, amount: 1170 });
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.httpStatus);        // 400, ou 0 si injoignable sur le LAN
    console.log(err.getErrorText());    // ex: "ZeroconfException error message Amount cannot be null"
    console.log(err.responseBody?.raw); // chaîne brute du terminal (si 400 non-JSON)

    if (err.httpStatus === 0) {
      // Terminal injoignable — vérifier IP/port/réseau
    }
  } else {
    throw err;
  }
}

Variantes Merchant vs ISV Merchant vs ISV variants

Chaque endpoint existe en deux variantes : merchant (sans slash final) et ISV (avec slash final, ex : /pos/v1/sale/). Un seul jeu de méthodes + le toggle global useIsvEndpoints gère les deux.

const terminal = new VivaLocalTerminalClient({
  terminalBaseUrl: "https://192.168.1.50:8080",
  useIsvEndpoints: true,
});

await terminal.transactions.sale({
  sessionId,
  amount: 1170,
  isvDetails: { /* objet partenaire / fee / multi-marchand ISV */ },
});

isvDetails est omis du corps quand il est undefined — inoffensif pour les appels merchant.

Changelog v1.0.0

• Modèle P2P sans authentification : communication directe avec le terminal sur le LAN, aucun header Authorization.
• TLS configurable (verifyTls: false ou dispatcher undici personnalisé) pour certificats auto-signés.
• Ressource Transactions : sale(), capturePreauth(), refund(), unreferencedRefund(), abort(), aadeFimControl(), retrieve().
• Ressource Sessions : get() (polling du résultat).
• Ressource Device : screenControl(), brightness().
• Enums : SessionState, SessionType, TransactionTypeId, PaymentMethod.
• Variantes Merchant et ISV via useIsvEndpoints.
• Erreurs 400 préservées en chaîne brute ; ApiError avec httpStatus === 0 sur terminal injoignable. TypeScript strict, ESM + CJS + .d.ts.