Cos’è l’integrazione locale?
L’integrazione locale consente al software della cassa di inviare richieste di pagamento direttamente al terminale di pagamento Vivid tramite la rete locale (Wi-Fi o cablata). Il terminale continua a connettersi al cloud di Adyen per l’autorizzazione e il regolamento — il software comunica semplicemente con esso in locale.
Questa guida è rivolta ai commercianti e ai loro fornitori di software che desiderano effettuare la configurazione da soli.
Prima di iniziare
Assicurati di avere:
Un terminale di pagamento Vivid già configurato e collegato all’account commerciante.
Un software della cassa in grado di inviare richieste HTTPS (il tuo o quello del tuo fornitore).
Una rete locale in cui la cassa e il terminale possano raggiungersi a vicenda.
Una passphrase di crittografia configurata nell’app Vivid o sul web (descritta nel Passaggio 3).
Passaggio 1. Configura la rete
Assicurati che le seguenti porte siano aperte sul firewall:
Connessione | Porta | Perché |
Terminale di pagamento → Internet | TCP 443 | Il terminale comunica con Adyen |
Cassa → Terminale di pagamento | TCP 8443 | Richieste di pagamento locali |
Inserisci questi due domini nella lista consentiti per nome (non per IP — gli indirizzi IP di Adyen cambiano):
*.adyen.com
*.adyenpayments.com
Altre due cose:
Non configurare il firewall per ispezionare o declassare il traffico TLS verso il terminale — questo interromperà la connessione.
Assegna a ogni terminale un indirizzo IP fisso (tramite prenotazione DHCP o IP statico) in modo che la cassa sappia sempre dove trovarlo.
Passaggio 2. Installa una libreria Adyen (facoltativo ma consigliato)
Adyen offre librerie open source gratuite che si occupano della maggior parte del lavoro tecnico nei Passaggi 3 e 4. Se il software della cassa è basato su una di queste piattaforme, consigliamo di usare la libreria corrispondente:
Piattaforma | Libreria |
Java | |
.NET | |
Node.js | |
iOS |
Se la tua piattaforma non è elencata, puoi comunque completare l’integrazione manualmente.
Passaggio 3. Configura la crittografia
Per mantenere al sicuro i dati di pagamento sulla rete locale, devi configurare una chiave di crittografia condivisa tra il terminale e il software della cassa. Questo si compone di tre parti.
Configura la chiave di crittografia nell’app Vivid:
Nell’app Vivid o sul web, vai su Impostazioni del terminale di pagamento > Chiave di crittografia e compila:
Identificatore della chiave — un nome per la chiave.
Passphrase della chiave — almeno 12 caratteri, con almeno una lettera maiuscola, una minuscola, un numero e un carattere speciale.
Versione della chiave — un numero di versione (un qualsiasi numero intero positivo).
Tocca Salva. I valori verranno nascosti dopo il salvataggio — usa l’icona a forma di occhio per visualizzarli. Per eliminare la chiave, svuota tutti e tre i campi e tocca Salva.
Le chiavi diventano effettive alla successiva connessione del terminale alla piattaforma, che di solito avviene ogni tre ore. Puoi anche attivarla manualmente tramite Impostazioni sul terminale.
Installa il certificato radice di Adyen:
La cassa deve fidarsi del certificato di sicurezza di Adyen per verificare che stia comunicando con il terminale corretto.
Scarica e installa il certificato seguendo le istruzioni per il tuo sistema operativo: https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local#install-root-cert
Riavvia il software della cassa dopo l’installazione.
Configura il software della cassa:
Il software della cassa deve fare due cose a ogni richiesta di pagamento:
Verificare il certificato del terminale rispetto al certificato radice di Adyen. Non saltare mai questo passaggio e non ripiegare mai su una connessione non crittografata.
Crittografare la richiesta usando la passphrase condivisa dell’app Vivid.
Se usi la libreria Adyen del Passaggio 2, tutto questo è gestito automaticamente — basta fornire la passphrase e il percorso del certificato.
Se procedi manualmente, segui la documentazione sulla crittografia di Adyen (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local) per implementare il pinning del certificato, la derivazione della chiave e la crittografia dei messaggi.
Passaggio 4. Invia le richieste di pagamento
Il software della cassa invia le richieste di pagamento al terminale all’indirizzo:
Il terminale risponde sulla stessa connessione. Se usi la libreria Adyen, richiama il metodo sincrono appropriato. Se procedi manualmente, costruisci la richiesta JSON, crittografala come descritto nel Passaggio 3 e inviala tramite POST.
Passaggio 5. Gestisci connessioni lente o perse
Le transazioni di pagamento a volte possono richiedere un po’ di tempo — ad esempio, se un cliente ha bisogno di più tempo per inserire il PIN. Assicurati che il software della cassa:
Attenda almeno 120 secondi prima di mandare in timeout una richiesta di pagamento.
Se non c’è risposta dopo 150 secondi, controlli automaticamente lo Stato della transazione prima di considerare il pagamento fallito.
Abbia un’opzione manuale Controlla ultima transazione che consenta al personale di risolvere situazioni poco chiare.
Registri ogni richiesta e risposta, inclusi ServiceID, SaleID e POIID — saranno necessari se contatti l’assistenza.
Di cosa è responsabile Vivid
Vivid fornisce il terminale di pagamento e lo configura sull’account commerciante. Tutto ciò che è descritto in questa guida — configurazione di rete, certificati, crittografia e software della cassa — è responsabilità tua (o del tuo fornitore). Vivid non fornisce assistenza né certifica le integrazioni del software della cassa.
Per assistenza sul terminale stesso — attivazione, hardware o chiave di crittografia lato terminale — contatta l’assistenza Vivid.
Importante: non modificare il terminale di pagamento. Non devi installare software su di esso, manomettere il firmware o interferire con la sua connessione ad Adyen. Farlo invalida la certificazione, viola la conformità PCI e può comportare la disattivazione remota del terminale.
Domande frequenti
Vivid aiuta a configurare il mio software della cassa?
No — l’integrazione del software della cassa è responsabilità tua o del tuo fornitore. Per indicazioni tecniche, consulta la documentazione dell’API Terminal di Adyen (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local).
La chiave di crittografia non appare sul terminale — cosa devo fare?
Le chiavi vengono applicate alla successiva connessione del terminale alla piattaforma, che di solito avviene ogni tre ore. Puoi anche attivarla manualmente tramite Impostazioni sul terminale. Se il problema persiste, contatta l’assistenza Vivid.
Posso usare una rete cablata?
Sì, funzionano sia le reti cablate sia quelle Wi-Fi, purché la cassa e il terminale siano sulla stessa rete e le porte del Passaggio 1 siano aperte.
Come aggiorno o rimuovo la chiave di crittografia?
Vai su Impostazioni del terminale di pagamento > Chiave di crittografia nell’app Vivid o sul web. Inserisci nuovi valori e tocca Salva per aggiornare. Svuota tutti e tre i campi e tocca Salva per rimuovere la chiave.