Il tokenization SDK di PCI Proxy EU permette ai team di sviluppo di integrare la conformità PCI DSS direttamente nel codice applicativo, senza costruire infrastrutture di sicurezza da zero. Disponibile per i tre linguaggi backend più diffusi, l'SDK gestisce autenticazione, cifratura in transito e gestione degli errori, lasciando al developer solo la logica di business. Questo articolo mostra i pattern di integrazione principali con esempi concreti.
SDK PCI Proxy EU: struttura e autenticazione
L'SDK espone un client singleton che si inizializza con la API key e l'ambiente (sandbox o produzione). L'autenticazione avviene tramite header Bearer su ogni richiesta HTTP verso gli endpoint PCI Proxy EU. Il client gestisce automaticamente il retry con backoff esponenziale per errori transitori (timeout, 429 rate limit) e solleva eccezioni tipizzate per errori permanenti come token non trovato o carta scaduta.
La struttura del package segue le convenzioni di ogni linguaggio: moduli CommonJS/ESM per Node.js, package PyPI per Python, package Composer per PHP. Ogni release è firmata e pubblica un SBOM (Software Bill of Materials) per facilitare la compliance alle policy di supply chain security. Il changelog documenta breaking change e aggiornamenti ai requisiti PCI.
Tokenizzazione in Node.js: esempio pratico
In un backend Node.js con Express, il flusso tipico prevede di ricevere il token generato dal frontend hosted field, chiamare il metodo client.charge(token, amount, currency) e gestire la risposta. L'SDK restituisce un oggetto strutturato con l'esito dell'autorizzazione, l'identificativo della transazione e i metadati necessari per la riconciliazione. In caso di rifiuto, la risposta include il codice di rifiuto ISO e un messaggio localizzato.
Per i pagamenti ricorrenti, il metodo client.detokenize(token) recupera un riferimento al PAN valido per una singola charge verso il processore. Il riferimento è monouso e scade dopo pochi secondi, impedendo che possa essere riutilizzato da un attaccante che intercettasse la chiamata. Il developer non riceve mai il PAN in chiaro: riceve solo il riferimento temporaneo che il proxy usa internamente.
Python e PHP: le stesse funzionalità, la stessa semplicità
L'SDK Python segue le convenzioni della libreria requests e supporta sia l'uso sincrono che asincrono tramite asyncio. L'inizializzazione avviene con PCIProxyClient(api_key=os.environ["PCI_PROXY_KEY"]), e tutti i metodi accettano dizionari Python nativi per i parametri. La gestione degli errori usa eccezioni della gerarchia PCIProxyError, con sottoclassi per errori di autenticazione, validazione e di rete.
Per PHP, il package Composer installa automaticamente le dipendenze Guzzle per le chiamate HTTP. Il client usa interfacce PSR-7 e PSR-18, rendendolo compatibile con qualsiasi framework che segua gli standard PHP-FIG, da Laravel a Symfony. I metodi sono documentati con PHPDoc completo e il package include tipi stub per IDE. In entrambi i linguaggi, la transizione dalla sandbox alla produzione richiede solo di cambiare la variabile d'ambiente con la chiave di produzione.
Domande frequenti
L'SDK è open source?
Il codice sorgente dell'SDK è disponibile su GitHub con licenza MIT. Chiunque può ispezionare l'implementazione, segnalare issue e proporre pull request. Il core del vault e della cifratura rimane lato server su PCI Proxy EU, ma il codice client che il developer usa nella propria applicazione è completamente trasparente e auditabile.
Come gestisco gli errori di tokenizzazione nell'SDK?
Ogni metodo dell'SDK può sollevare eccezioni tipizzate che corrispondono a categorie di errore specifiche. Gli errori di rete e timeout sono gestiti automaticamente dal meccanismo di retry. Gli errori semantici come carta non valida o token scaduto vengono propagati con codici e messaggi standardizzati che permettono di restituire al cliente un messaggio appropriato senza esporre dettagli tecnici interni.
L'SDK supporta il detokenization per charge ricorrenti?
Il metodo di detokenizzazione è progettato specificamente per i pagamenti ricorrenti e le sottoscrizioni. Il token viene creato una volta durante il primo pagamento o durante la fase di registrazione carta, e poi riutilizzato per ogni charge successiva senza che il cliente debba reinserire i dati. Il token non ha scadenza di default, ma può essere configurato con una data di scadenza esplicita per rispettare le policy aziendali.
Pronto a integrare il tokenization SDK nel tuo stack? Accedi alla documentazione e alla sandbox e vai in produzione in pochi giorni. Scopri PCI Proxy EU.