Una chiave API di pagamento funziona come una carta di prelievo senza PIN. Chi la invia può creare fatture, leggere i tuoi dati di pagamento e, se usi i pagamenti in uscita, spostare denaro dal tuo saldo. La sicurezza delle API di pagamento si riduce quindi a tre abitudini: conservare la chiave sui tuoi server, far accettare l'API solo dagli indirizzi di quei server e confermare ogni webhook rileggendo il pagamento prima di agire.
Questa guida è rivolta ai responsabili tecnici e ai responsabili dei pagamenti di PSP (prestatori di servizi di pagamento), EMI (istituti di moneta elettronica), banche ed esercenti che collegano un'API di pagamento in criptovalute con regolamento in euro. Mostra come limitare una chiave per indirizzo IP e intervallo CIDR, dove deve trovarsi la chiave, come verificare i webhook e quali controlli applicare ai pagamenti in uscita. Gli esempi usano l'API e la dashboard di ItisPay (dati dimostrativi).
Momenti chiave
In sintesi
- Una chiave API è una credenziale al portatore. GitGuardian ha contato 28,65 milioni di nuovi segreti hardcoded nei commit pubblici su GitHub nel 2025, quindi metti in conto che una chiave possa trapelare, non solo di custodirla in sicurezza.
- Un'allowlist IP rende inutile una chiave trapelata al di fuori della tua rete. Inserisci gli intervalli IPv4 o IPv6 più piccoli che coprono i tuoi reali indirizzi in uscita; una lista vuota consente ogni indirizzo.
- Un webhook è un avviso, non una prova. Rileggi la fattura tramite il suo ID con la tua chiave prima di spedire merci o accreditare un conto.
- I pagamenti in uscita richiedono controlli umani da parte tua: accesso in due passaggi, IBAN e wallet dei beneficiari salvati e un secondo approvatore oltre un importo stabilito.
Perché una chiave API di pagamento trapelata è così pericolosa?#
Una chiave API di pagamento trapelata è pericolosa perché la chiave rappresenta l'intera identità della tua integrazione. L'API di ItisPay, come la maggior parte delle API di pagamento, autentica ogni richiesta con un solo header, Api-key, e la stessa autenticazione copre le fatture, i pagamenti verso un IBAN o un wallet e i prelievi di criptovalute verso un indirizzo esterno. Per questo la documentazione chiede che la chiave « non sia esposta nel codice lato client o in repository pubblici ».
In pratica le chiavi trapelano attraverso luoghi ordinari: codice, log e chat. Secondo GitGuardian's State of Secrets Sprawl 2026 (marzo 2026), nel 2025 sono stati aggiunti 28,65 milioni di nuovi segreti incorporati nei commit pubblici su GitHub, il 34% in più rispetto all'anno precedente. Quando GitGuardian ha ritestato i segreti trapelati nel 2022, a gennaio 2026 oltre il 64% risultava ancora valido. I team pubblicano le chiavi e poi dimenticano di sostituirle.
L'OWASP API Security Top 10 (2023) classifica al secondo posto la voce « Broken Authentication » e avverte che « il meccanismo di autenticazione è un bersaglio facile per gli attaccanti, perché è esposto a tutti ». Il Data Breach Investigations Report 2025 di Verizon indica l'abuso di credenziali come il vettore d'attacco iniziale più comune, con il 22%. Una semplice stringa segreta è una difesa fragile, quindi il resto di questa guida aggiunge livelli che reggono anche quando la stringa è già uscita.
In che modo un'allowlist IP protegge una chiave API?#
Un'allowlist IP, talvolta chiamata whitelist IP, protegge la chiave legandola sia a dei luoghi sia a una stringa. L'API accetta la chiave solo quando la richiesta arriva da un indirizzo che hai inserito nella lista; una copia della chiave sul portatile di uno sviluppatore, in un log di CI o su un sito di condivisione di testi non funziona.
Nella dashboard di ItisPay l'impostazione si trova in Projects, poi Settings, poi Security, nel campo « API Allowed IPs ». Il campo accetta un elenco separato da virgole di singoli indirizzi e blocchi CIDR. Il suo testo di aiuto dice: « Lascia vuoto per consentire tutti gli IP. Sono supportati sia IPv4 sia IPv6. » La stessa lista può essere impostata alla creazione di un progetto tramite API, nel campo api_allowed_ips, e una voce non valida, come 256.256.256.256, viene rifiutata con un errore di validazione invece di essere salvata.
Il valore predefinito vuoto conta. Un nuovo progetto accetta la chiave da qualsiasi luogo finché qualcuno non compila il campo, quindi inserisci questo passaggio nella lista delle cose da fare prima del go-live, non in quella delle cose da sistemare più avanti. I valori dimostrativi nello screenshot, 203.0.113.10 e 198.51.100.0/24, provengono da intervalli che la RFC 5737 riserva alla documentazione; la tua lista conterrà i tuoi indirizzi pubblici. Ogni progetto ha la propria chiave di 64 caratteri e la propria lista, quindi la produzione può restare limitata a due o tre server, mentre un progetto di test può accettare un insieme più ampio.
Come si scrivono gli intervalli CIDR per IPv4 e IPv6?#
Scrivi l'intervallo più piccolo che copra ogni indirizzo che i tuoi server usano davvero per raggiungere l'API. La maggior parte dei problemi con le allowlist deriva da un intervallo troppo ampio o da un percorso in uscita che qualcuno ha dimenticato.
Come leggere un prefisso#
Un blocco CIDR è un indirizzo seguito da una barra e dalla lunghezza del prefisso. La RFC 4632 definisce la lunghezza del prefisso come il numero di bit significativi: 192.168.99.0/24 fissa i primi 24 bit e ne lascia 8 liberi, il che dà 256 indirizzi. Ogni bit che sottrai al prefisso raddoppia il blocco. Un /32 è un indirizzo IPv4, un /29 ne contiene 8, un /24 ne contiene 256 e un /16 ne contiene 65.536.
IPv6 funziona allo stesso modo con 128 bit. Un /128 è un singolo indirizzo. La RFC 4291 fissa a 64 bit la parte di interfaccia della maggior parte degli indirizzi IPv6, quindi la rete di un server è normalmente un /64 e l'host può cambiare il proprio indirizzo al suo interno, ad esempio quando il sistema operativo genera indirizzi temporanei. Se l'indirizzo IPv6 del tuo host cambia e quel /64 è esclusivamente tuo, inserisci il /64 anziché un singolo /128. L'intervallo di documentazione per gli esempi IPv6 è 2001:db8::/32 (RFC 3849), quindi non copiarlo mai in una allowlist reale.
Trovare il tuo indirizzo reale in uscita#
L'indirizzo che conta è quello che vede l'API, non quello che il tuo server riporta di sé. Dietro un gateway NAT cloud o un firewall aziendale, molte macchine condividono uno o due indirizzi pubblici. Le funzioni serverless spesso escono da un pool condiviso, a meno che non le instradi attraverso un egress fisso. Verifica da ogni ambiente chiamando un servizio «qual è il mio IP» oppure leggi l'indirizzo sorgente nei log del firewall, quindi inserisci esattamente quello.
| Configurazione | Cosa inserire | Verdetto |
|---|---|---|
| Un server con indirizzo IPv4 pubblico statico | Quell'indirizzo come /32 o semplice | Funziona |
| Più server dietro un gateway NAT cloud | Gli indirizzi pubblici del gateway NAT | Funziona |
| Host IPv6 con indirizzi che cambiano | Il /64 dell'host, se nessun altro lo usa | Dipende |
| Rete d'ufficio per test manuali | L'indirizzo fisso dell'ufficio, se il provider lo garantisce | Dipende |
| Funzioni serverless senza uscita fissa | Instradarle prima attraverso un NAT con indirizzo statico | No |
| L'intero intervallo regionale di un provider cloud | Nulla; copre anche altri clienti | No |
Prima di salvare una modifica, aggiungi prima il nuovo indirizzo, esegui il deploy, verifica che il traffico scorra e solo dopo rimuovi quello vecchio. Salvare una lista che non include i tuoi server attivi blocca il tuo checkout.
Dove deve risiedere la chiave API e chi la vede?#
La chiave deve stare sui tuoi server, in un secret store, e in nessun altro posto. Non inserirla mai in una pagina del browser o in un'app mobile, perché chiunque può leggerla lì. Tienila fuori anche dagli URL: l'OWASP REST Security Cheat Sheet avverte che una chiave in un URL può essere catturata nei log del server web. La tua pagina di checkout parla con il tuo back end; il back end parla con l'API di pagamento.
Carica la chiave da un gestore di segreti o da variabili d'ambiente all'avvio, non da un file di configurazione nel repository. Se ospiti il codice su GitHub, attiva la push protection: secondo la documentazione di GitHub, quando rileva « un potenziale segreto durante un tentativo di push, bloccherà il push ».
Usa una chiave per ogni ambiente. Ogni progetto ItisPay ha la propria chiave e la propria allowlist, quindi progetti separati per produzione e staging significano che una chiave di staging trapelata non può toccare i pagamenti reali. Limita chi può vedere la chiave di produzione. Le linee guida dell'Autorità bancaria europea (EBA) del 2019 sulla sicurezza ICT fissano la regola del « need-to-know » con « diritti di accesso minimi », inclusi gli utenti tecnici; dal 2025 il DORA impone questo obbligo alla maggior parte delle imprese di pagamento.
Poi documenta come sostituiresti la chiave, prima di averne bisogno. L'OWASP Cryptographic Storage Cheat Sheet raccomanda di ruotare le chiavi dopo un periodo stabilito e ogni volta che si sospetta una compromissione, e di assicurarsi che « il codice e i processi necessari per ruotare una chiave siano in essere prima che siano richiesti ».
Come verificare i webhook di un'API di pagamento?#
Considera un webhook come un avviso che qualcosa è cambiato, mai come prova che sei stato pagato. Chiunque conosca il tuo URL di callback può inviargli un falso messaggio « completed ». Lo schema sicuro è rileggere la fattura dall'API con la tua chiave e agire su ciò che l'API restituisce.
Quando crei una fattura ItisPay, il campo callback_url imposta l'indirizzo per gli aggiornamenti di stato. Quando arriva un webhook, prendi da esso l'ID della fattura, esegui una GET sulla fattura tramite ID, e spedisci o accredita solo se la risposta mostra lo stato che ti aspetti e l'importo che hai fissato. La documentazione descrive questo endpoint, che restituisce lo stato del pagamento e i dettagli blockchain, « per la visualizzazione agli utenti o per la verifica ».
Alcune regole mantengono il gestore pulito:
- Accetta webhook solo via HTTPS e rifiuta l'HTTP semplice.
- Rendi il gestore idempotente. Memorizza ogni ID fattura elaborato e il relativo stato, e salta le ripetizioni, perché i provider rinviano gli avvisi.
- Rispondi rapidamente e svolgi il lavoro in una coda, così un database lento non innesca nuovi tentativi.
- Se un provider firma i suoi webhook con HMAC, un hash con chiave definito nella RFC 2104, ricalcola la firma e confrontala con una funzione a tempo costante. L'OWASP Webhook Security Cheat Sheet è netto: « Non usare mai ==: perde informazioni sui tempi e può trasformare l'endpoint in un oracolo di firma. » Rifiuta i messaggi il cui timestamp firmato è troppo vecchio.
Testa prima del go-live. ItisPay ha un endpoint che simula un cambio di stato per una fattura di test reale e un altro che reinvia l'ultimo webhook per un ID fattura o ordine, così puoi verificare retry e duplicati senza denaro reale.
Come proteggere i pagamenti in uscita e l'accesso alla dashboard?#
I payout sono il punto in cui una chiave rubata si trasforma in denaro perso, quindi aggiungi controlli umani attorno ad essi. Tramite l'endpoint payout di ItisPay, un payout in valuta fiat va a un IBAN del beneficiario e un payout crypto a un indirizzo wallet, entrambi dal tuo saldo disponibile. L'API fa ciò che la richiesta dice; decidere se una richiesta è legittima spetta a te.
Controlli efficaci dal tuo lato:
- Autenticazione in due passaggi per tutti quelli con accesso alla dashboard o ai payout. Il diritto dei pagamenti dell'UE usa già questa idea per gli utenti di pagamento: le regole PSD2 sull'autenticazione forte del cliente richiedono almeno due elementi indipendenti tra conoscenza, possesso e inerenza. Applica lo stesso standard al tuo personale.
- Beneficiari salvati. Mantieni la tua lista di IBAN e indirizzi wallet approvati, e fai in modo che il servizio di payout invii solo verso voci presenti in essa. Un nuovo beneficiario passa per un'approvazione separata, idealmente con un periodo di attesa.
- Un secondo approvatore sopra una soglia. Uno prepara, un altro approva. Imposta l'importo in base alla tua propensione al rischio.
- Un servizio di payout separato. Esegui i payout da un servizio con un proprio indirizzo fisso nella allowlist, separato dai server di checkout che creano le fatture.
| Controllo | Cosa blocca | Esito |
|---|---|---|
| Allowlist IP sulla chiave | Uso di una chiave trafugata da fuori della propria rete | Funziona |
| Chiave solo sul server | Furto della chiave da browser, app e repository | Funziona |
| Rilettura della fattura dopo un webhook | Falsi avvisi di «pagato» | Funziona |
| Beneficiari salvati e secondo approvatore | Pagamenti verso l'IBAN o il wallet di un aggressore | Funziona |
| Ciascuno di questi controlli da solo contro un server compromesso presente nell'elenco | Furto da parte di chi è già all'interno | No |
Cosa si aspettano DORA e PCI DSS dall'accesso alle API?#
Se sei un'entità finanziaria regolamentata nell'UE, questi controlli non sono extra facoltativi. Il Digital Operational Resilience Act (DORA, regolamento (UE) 2022/2554) si applica dal 17 gennaio 2025, secondo l'EBA. Il suo articolo 9 chiede alle entità finanziarie di «attuare politiche che limitino l'accesso fisico o logico» agli asset ICT e di «attuare politiche e protocolli per meccanismi di autenticazione forte». Una chiave inserita in allowlist, utilizzabile solo dal server e con un piano di rotazione, è il tipo di evidenza che un revisore chiede di vedere.
Il PCI DSS riguarda i dati delle carte, non le fatture in criptovaluta. Se lo stesso team gestisce anche pagamenti con carta, il requisito 8.4.2 richiede l'autenticazione a più fattori per ogni accesso all'ambiente dei dati del titolare della carta, e i requisiti con data di efficacia futura della versione 4.0 sono diventati obbligatori il 31 marzo 2025.
Dove smettono di funzionare i controlli di sicurezza delle API di pagamento?#
Questi controlli riducono le modalità di accesso. Da soli non rendono sicura un'integrazione. Anche per i mittenti di webhook, la scheda OWASP sui webhook definisce l'allowlist IP «solo un livello aggiuntivo», perché «un IP di uscita condiviso non è una prova di identità».
Dove non aiuta
- Un server compromesso presente nell'allowlist. L'aggressore invia richieste da un indirizzo attendibile con la chiave reale.
- Indirizzi di uscita condivisi. Se altri tenant escono dal cloud dallo stesso indirizzo NAT, l'allowlist non riesce a distinguerli da te.
- Una password della dashboard rubata senza accesso in due passaggi. L'aggressore salta del tutto l'API.
- Dati personali nei campi della fattura. L'endpoint pubblico delle fatture di ItisPay restituisce tutti i dettagli delle fatture aperte senza chiave, quindi non inserire nomi e email dei clienti nel nome dell'ordine.
Come si avvia un'integrazione sicura in un solo pomeriggio?#
Puoi completare la parte tecnica di un'integrazione sicura in un pomeriggio, se segui un ordine preciso. I passaggi seguenti usano ItisPay; lo stesso ordine funziona con qualsiasi provider.
- Crea un progetto di test e un progetto di produzione separato, ciascuno con la propria chiave.
- Conserva entrambe le chiavi nel tuo gestore di segreti e caricale solo sul server.
- Individua l'indirizzo di uscita pubblico di ciascun ambiente e inseriscilo in API Allowed IPs.
- Crea una fattura dal back end: POST verso https://api.itispay.com/api/v1/invoices con l'header Api-key, un order_id univoco, fiat_amount con fiat_currency EUR, la criptovaluta in currency e il tuo callback_url.
- Costruisci il gestore dei webhook: solo HTTPS, idempotente, con rilettura della fattura tramite ID prima di qualsiasi azione.
- Esegui la simulazione dei webhook per ogni stato che gestisci, poi l'endpoint di reinvio per testare i duplicati.
- Attiva i pagamenti in uscita per ultimi, con beneficiari salvati e un secondo approvatore.
Per iniziare rapidamente, l'assistente Ask AI nella dashboard scrive, su richiesta, codice di esempio, ad esempio una chiamata per la creazione di una fattura in Node.js con l'header Api-key già inserito. Consideralo una bozza: verifica i nomi dei campi con il riferimento API prima della messa in produzione, perché è il riferimento, non un esempio generato, a fare da contratto. ItisPay pubblica inoltre un client TypeScript ufficiale su npm, @itispay/typescript-client.
Se inserisci questa integrazione in un'architettura più ampia di orchestrazione dei pagamenti, assegna a ciascun provider la propria chiave, la propria allowlist e il proprio gestore di webhook. Lo stesso record riletto tramite ID alimenta anche la riconciliazione dei pagamenti in criptovaluta per il tuo team finanziario.
Se vuoi accettare pagamenti in stablecoin e ricevere euro senza costruire lo stack da solo, ItisPay fornisce API, fatturazione, webhook e riconciliazione, oltre al primo livello di sicurezza delle API di pagamento: chiavi che puoi limitare ai tuoi indirizzi IP. Le autorizzazioni, il KYC e il regolamento sul tuo IBAN passano per il nostro partner autorizzato nell'UE come prestatore di servizi per le cripto-attività (CASP) e istituto di pagamento, e la maggior parte dei team passa da KYB alla prima transazione in meno di una settimana.
Questo articolo ha scopo esclusivamente informativo e non costituisce consulenza legale o regolamentare.
