Come funziona PCI Proxy
Tu ci mandi i dati carta. Noi li tokenizziamo, li custodiamo nel vault PCI DSS e ti restituiamo un token. Nei tuoi sistemi non finisce mai il numero di carta.
Tu mandi
Noi custodiamo
PCI DSS · UE Cifrati qui Tu ricevi
Il flusso in 5 passi
Dal momento in cui il cliente inserisce la carta fino al token che salvi nel tuo gestionale: ecco cosa succede passo per passo.
Dati carta in ingresso
Checkout sul sito, chiamata API o modulo call center
PCI Proxy intercetta
Riceviamo i dati carta dal payload HTTP prima che arrivino ai tuoi server
Tokenizzazione
Cifriamo il numero di carta e generiamo un token univoco
Vault sicuro
Il numero di carta resta cifrato nel vault PCI DSS Livello 1, solo in UE
Token a te
Ricevi il token e lo usi per pagamenti, abbonamenti o rimborsi
Cosa succede quando tokenizziamo
Sostituiamo il numero di carta con un token. Tu non vedi mai la carta in chiaro nei tuoi sistemi. Ecco i tre passaggi interni.
Passo
Riconosciamo i dati carta
Analizziamo le richieste in entrata e individuiamo i numeri di carta, su JSON, form o multipart. Non devi cambiare il tuo codice: ci colleghi il flusso e basta.
Passo
Creiamo il token
Ogni token inizia con tok_pci_eu_ e include le ultime quattro cifre, il circuito e la scadenza. Così in interfaccia puoi mostrare "Visa che termina con 1234" senza avere il numero di carta.
Passo
Stesso token, stessa carta
Se la stessa carta arriva di nuovo, restituiamo lo stesso token. Utile per abbonamenti e carte già salvate. La mappatura resta solo nel vault, non è esposta via API.
→ POST /v1/tokenize
{
"card_number": "4111 1111 1111 1234",
"expiry": "12/26"
}
← 200 OK · 47ms
{
"token": "tok_pci_eu_a1b2c3d4e5f61234",
"last_four": "1234",
"brand": "visa",
"carta_nei_tuoi_sistemi": false
}
Quando serve il numero di carta
Per autorizzare un pagamento il PSP ha bisogno del numero di carta reale. Tu gli mandi il token: noi recuperiamo la carta dal vault e la inoltriamo in modo sicuro. Tu non la vedi mai.
Quando succede
Quando devi addebitare una carta salvata, invii il token al nostro endpoint forward. Noi risolviamo il numero di carta nel vault e lo passiamo al PSP via connessione cifrata. Non compare nei tuoi log.
Chi può farlo
Solo chi ha una chiave API con permesso forward o detokenize. Puoi limitare per IP, ambiente e volume di richieste.
Tutto tracciato
Ogni recupero viene registrato: chi ha chiesto, quando, verso quale PSP. I log restano almeno 12 mesi e li puoi consultare da dashboard o API.
Livelli di protezione
Ogni richiesta è autenticata
Solo dai tuoi server autorizzati
TLS con certificati verificati
Conservati almeno 12 mesi
Due endpoint, flusso chiaro
Autenticati con la tua chiave API. Un endpoint crea il token, l'altro lo usa per pagare. JSON in entrata, JSON in uscita.
/v1/tokenize Scope: tokenize Corpo della richiesta
{ "card_number": "4111111111111111", "expiry": "12/26", "cvv": "123" }
Risposta 200 OK
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "last_four": "1111", "brand": "visa", "expires_at": "2026-12-31" }
/v1/forward Scope: forward Corpo della richiesta
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "target_url": "https://psp.eu/charge", "amount": 9900, "currency": "EUR" }
Risposta (dal PSP, proxyata)
{ "status": "authorized", "transaction_id": "txn_9f8e7d6c", "amount": 9900, "currency": "EUR" }
Webhook e notifiche
Quando succede qualcosa (token creato, pagamento inviato, errore), ti mandiamo un evento in tempo reale sul tuo endpoint. Ogni messaggio è firmato: puoi verificarlo lato server.
Se la consegna fallisce, riproviamo fino a 5 volte con intervalli crescenti. Puoi anche rilanciare manualmente dalla dashboard entro 72 ore.
Tipi di Eventi Supportati
token.created Nuovo token generato token.used Token inviato al PSP token.expired Token ha raggiunto il TTL token.deleted Token rimosso su richiesta forward.success PSP ha restituito 2xx forward.failure PSP ha restituito errore Esempio di Payload Webhook
tuo-server.com/webhooks/pci LIVE
{
"event": "token.created",
"timestamp": "2026-04-03T10:15:30Z",
"data": {
"token": "tok_pci_eu_a1b2c3d4e5f6",
"last_four": "1111",
"brand": "visa",
"merchant_id": "mrc_xyz789"
},
"signature": "sha256=4a8b9c..." // HMAC-SHA256
}Verifica della firma
Ogni webhook include l'header X-PCI-Signature. Calcola HMAC-SHA256 del body con il tuo secret e confrontalo con la firma. Se non coincide, rifiuta la richiesta.
SDK e modi per integrarti
SDK in Node, Python e PHP, oppure campi hosted in iFrame. Scegli quello che si adatta al tuo stack.
SDK JavaScript
npmimport PCIProxy from '@pci-proxy-eu/js';
const pci = new PCIProxy({
merchantId: 'mrc_xyz789'
});
const { token } = await pci.tokenize({
cardNumber: '4111...'
});SDK Python
PyPIfrom pci_proxy_eu import Client
client = Client(
merchant_id="mrc_xyz789",
api_key="sk_live_..."
)
result = client.tokenize(
card_number="4111..."
)SDK PHP
Composeruse PCIProxyEU\Client;
$client = new Client(
merchantId: 'mrc_xyz789',
apiKey: 'sk_live_...'
);
$result = $client->tokenize([
'card_number' => '4111...'
]);iFrame sicuri per il checkout
Per restare in SAQ A: i campi carta sono renderizzati in iFrame nostri. I dati carta non passano mai dal tuo DOM.
<div id="card-number"></div>
<div id="card-expiry"></div>
<div id="card-cvv"></div>
<script>
PCIProxy.hostedFields({
merchantId: 'mrc_xyz789',
fields: {
cardNumber: '#card-number',
expiry: '#card-expiry',
cvv: '#card-cvv'
},
onTokenize: (result) => {
// solo token, mai il numero di carta
console.log(result.token);
}
});
</script>Dati di Pagamento
Dati carta mai sul tuo server
SAQ A
Meno obblighi PCI
CSS
Stile personalizzabile
Mobile
Responsive
Pronto a integrare?
Scopri cos'è un PCI Proxy, approfondisci la tokenizzazione o guarda come gli sviluppatori usano la piattaforma.