Viva Local Terminal PHP 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…) retournent 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 Composer. Requiert PHP 8.2+ avec l'extension ext-json.

Install via Composer. Requires PHP 8.2+ with the ext-json extension.

composer require qrcommunication/viva-local-terminal-sdk

Compatible avec Laravel, Symfony ou tout projet PHP standard.

Démarrage rapide Quick Start

<?php

use QrCommunication\VivaLocalTerminal\VivaLocalTerminalClient;

// 1. Pointer le client sur l'IP + port du terminal sur le LAN
$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
$sessionId = '4bdebe62-c211-4ca0-a994-b2fbea2061c5';
$resp = $terminal->transactions->sale(
    sessionId:         $sessionId,
    amount:            1170,        // 11,70 EUR
    currencyCode:      978,         // EUR
    merchantReference: 'order-123',
);
// $resp = ['state' => 'PROCESSING', 'sessionType' => 'SALE', 'sessionId' => ...]

// 3. Interroger le résultat une fois le client ayant payé
$session = $terminal->sessions->get($sessionId);
// $session['state'] === 'SUCCESS' une fois la carte traitée

// 4. Contrôler le terminal
$terminal->device->screenControl(wakeUpLock: true);
$terminal->device->brightness(0.5);

Configuration

Le constructeur VivaLocalTerminalClient n'accepte aucun identifiant (pas de clé API, client ID ou secret) — le modèle P2P est sans authentification.

The constructor 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é. Trois modes :

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

// 2. Pinner le bundle CA du terminal (recommandé en production)
$terminal = new VivaLocalTerminalClient(
    terminalBaseUrl: 'https://192.168.1.50:8080',
    verifyTls:       '/chemin/vers/terminal-ca.pem',
);

// 3. Désactiver la vérification (modèle de confiance LAN-only)
$terminal = new VivaLocalTerminalClient(
    terminalBaseUrl: 'https://192.168.1.50:8080',
    verifyTls:       false,
);

Ressources

$resp = $terminal->transactions->sale(
    sessionId:         '4bdebe62-c211-4ca0-a994-b2fbea2061c5',
    amount:            1170,        // 11,70 EUR
    currencyCode:      978,         // EUR
    merchantReference: 'order-123',
    showReceipt:       true,
);

echo $resp['state'];       // 'PROCESSING'
echo $resp['sessionType']; // 'SALE'

// Puis polling :
$session = $terminal->sessions->get($resp['sessionId']);

$resp = $terminal->transactions->capturePreauth(
    sessionId:     'a-new-uuid',
    amount:        1500,        // 15,00 EUR
    transactionId: 'preauth-transaction-id',
);

$resp = $terminal->transactions->refund(
    sessionId:     'a-new-uuid',
    amount:        1170,
    transactionId: 'original-sale-transaction-id',
);

$resp = $terminal->transactions->unreferencedRefund(
    sessionId: 'a-new-uuid',
    amount:    500, // 5,00 EUR
);

$terminal->transactions->abort('4bdebe62-c211-4ca0-a994-b2fbea2061c5');

$resp = $terminal->transactions->aadeFimControl(
    'ECR0210U/RCFB77000041/CMAC_K:1ED9F7AE0B2509281BBC2DE38EF2A12B:CC5FFF',
);
echo $resp['status'];  // 'success'
echo $resp['message']; // 'Fim control success'

$result = $terminal->transactions->retrieve(
    transactionTypes: [5, 4], // ventes + remboursements
    startDate:        '2026-03-01T00:00:00Z',
    endDate:          '2026-03-31T23:59:59Z',
);

foreach ($result['transactions'] ?? [] as $txn) {
    echo $txn['orderCode'] . PHP_EOL;
}

use QrCommunication\VivaLocalTerminal\Enums\SessionState;

do {
    $session = $terminal->sessions->get($sessionId);
    $state = $session['state'] ?? null;

    if ($state === SessionState::SUCCESS->value) {
        // Paiement réussi — $session['payloadData'] contient le détail
        break;
    }
    if ($state === SessionState::FAILURE->value) {
        break; // Paiement échoué
    }

    sleep(2);
} while ($state === SessionState::PROCESSING->value);

$resp = $terminal->device->screenControl(wakeUpLock: true);
echo $resp['isSuccess']; // true

$terminal->device->brightness(0.5); // 50 %
$terminal->device->brightness(1.0); // maximum
// $terminal->device->brightness(0.0); // ❌ InvalidArgumentException

Enums

Sous QrCommunication\VivaLocalTerminal\Enums.

SessionState

SessionType

TransactionTypeId

PaymentMethod

Gestion des erreurs Error Handling

Toutes les exceptions héritent de VivaException (extends RuntimeException).

RuntimeException
└── VivaException     (base — httpStatus, responseBody, getErrorText())
    └── ApiException  (levée sur 4xx ET sur terminal injoignable : httpStatus === 0)

use QrCommunication\VivaLocalTerminal\Exceptions\ApiException;
use QrCommunication\VivaLocalTerminal\Exceptions\VivaException;

try {
    $resp = $terminal->transactions->sale(sessionId: $sessionId, amount: 1170);

} catch (ApiException $e) {
    echo $e->httpStatus;          // 400, ou 0 si injoignable sur le LAN
    echo $e->getErrorText();      // ex: "ZeroconfException error message Amount cannot be null"
    echo $e->responseBody['raw']; // chaîne brute du terminal (si 400 non-JSON)

    if ($e->httpStatus === 0) {
        // Terminal injoignable — vérifier IP/port/réseau
    }

} catch (VivaException $e) {
    echo $e->getMessage();
}

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.

$terminal = new VivaLocalTerminalClient(
    terminalBaseUrl: 'https://192.168.1.50:8080',
    useIsvEndpoints: true,
);

$terminal->transactions->sale(
    sessionId:  $sessionId,
    amount:     1170,
    isvDetails: [/* objet partenaire / fee / multi-marchand ISV */],
);

isvDetails est omis du corps quand il vaut null — 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 : true / chemin PEM / false) 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 ; ApiException avec httpStatus === 0 sur terminal injoignable.