Passa al contenuto principale

Tokenizzazione

La tokenizzazione è un processo attraverso il quale i dati sensibili di una carta di pagamento vengono sostituiti da un token, ovvero un codice numerico o alfanumerico che rappresenta in modo univoco la carta, ma non contiene informazioni sensibili.

La tokenizzazione solleva l’esercente dall’onere di adeguarsi direttamente agli standard PCI DSS, in quanto i dati sensibili della carta non vengono gestiti o memorizzati sul sistema del merchant ma sui server del service provider (gateway di pagamento), che restituisce un token a norma PCI che è possibile archiviare nei propri sistemi.

Questa soluzione migliora sia la sicurezza sia l’esperienza di acquisto, consentendo al cliente di salvare più metodi di pagamento e velocizzare il checkout.

L'utilizzo del token rappresenta anche un requisito fondamentale per la gestione dei pagamenti ricorrenti

Tokenizzazione e APM

Il servizio di tokenizzazione è disponibile anche per alcuni APM che supportano la funzionalità. Per gli APM che supportano la tokenizzazione, è possibile ottenere un token rappresentativo dell’account del buyer, che non necessita di aggiornamento in quanto non rappresenta i dati della carta ma l’account del buyer.

Informativa obbligatoria al buyer

Prima di procedere con la tokenizzazione, il buyer deve essere informato che i dati della sua carta verranno tokenizzati. La responsabilità dell'informativa dipende da dove vengono raccolti i dati della carta:

  • Soluzioni Fabrick (pagina di pagamento Fabrick, Web Component) — l'informativa è già gestita. Quando la transazione include la richiesta di tokenizzazione, il sistema mostra automaticamente il messaggio direttamente sulla pagina, senza alcun intervento da parte dell'esercente.
  • Pagina di pagamento personalizzata (integrazione API Only) — l'informativa è a carico dell'esercente, che deve mostrare il messaggio al buyer prima dell'invio dei dati della carta.

Di seguito i messaggi mostrati automaticamente dalle soluzioni Fabrick: Tokenizzazione Tokenizzazione

Tipologie di Token​

I token carta possono appartenere a due categorie principali:

Token Proprietari​

Generati dal sistema Fabrick e gestiti dall’esercente.

  • Supportano tutte le tipologie di circuiti.
  • Se la carta è prossima alla scadenza, è necessario richiedere al buyer i dati aggiornati.
  • Se non possono essere convertiti in token di circuito, rimangono comunque validi per le transazioni.

Token di Circuito​

Generati e gestiti dai circuiti internazionali.

  • Disponibili per Visa e Mastercard.
  • Supportano aggiornamenti automatici dei dati della carta.
  • Riduzione del rischio di transazioni fallite per carta scaduta.
Risorse di approfondimento

Gestione Token​

Configurazione Backoffice​

Configura il Backoffice di Gestpay come indicato di seguito per ricevere in risposta l’oggetto TokenDetails.
Questa configurazione è necessaria per ottenere l'oggetto in risposta solo nei casi in cui la chiamata payment/submit non richiede il redirect del buyer per l’autenticazione, e il sistema restituisce immediatamente l’esito finale della transazione.

Configurazione:

  • No Display → per integrazioni che non utilizzano la pagina di pagamento Fabrick
  • Payment Page → per integrazioni che utilizzano la pagina di pagamento Fabrick

Tokenizzazione

Per tutte e due le configurazioni, abilita il campo TokenDetails nella sezione Campi & Parametri.

Tokenizzazione

Richiedere un Token​

Per generare un token è necessario avviare una transazione verso il buyer, in quanto il token deve essere autenticato.

La richiesta di tokenizzazione avviene aggiungendo alla chiamata il campo requestToken, valorizzato con MASKEDPAN, indicando così al sistema di generare il token e restituirlo nell’esito finale della transazione.

La tokenizzazione può essere richiesta solo attraverso una transazione.
L’importo della transazione può essere impostato a zero utilizzando un flusso di Non‑Payment Authentication (NPA).

Transazione a importo zero

Per maggiori dettagli sul flusso NPA, consulta la sezione dedicata: NPA — Non‑Payment Authentication.

Generazione del token

Non è possibile utilizzare metodi alternativi, come la chiamata POST shop/token, per generare un token in modo autonomo.

Durante la transazione il sistema:

  • verifica la correttezza delle date di scadenza inserite dal buyer
  • richiede l’autenticazione del titolare della carta

Al termine della transazione, sarà possibile ottenere in risposta il token della carta utilizzata.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
  "shopLogin": "GESPAY12345",
  "amount": "0.01",
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID",
  "requestToken": "MASKEDPAN" //servizio di tokenizzazione
}
Tokenizzazione per APM

Per i metodi di pagamento alternativi (APM) che supportano la tokenizzazione non è possibile utilizzare MASKEDPAN, in quanto questi servizi non si basano sui dati della carta ma sull’account del buyer. Ogni APM che supporta la tokenizzazione riporta nella relativa documentazione le modalità specifiche per richiedere il token del servizio.

Lettura Dati Token​

È possibile ottenere i dettagli del token tramite le seguenti API:

  • check/token
  • payment/detail
  • payment/submit (quando la chiamata non richiede il redirect del buyer per l’autenticazione)

Nel seguente esempio, utilizzando la chiamata payment/detail per interrogare una transazione completata per la quale era stato richiesto il token della carta.
Nella risposta, il sistema restituisce tra gli altri dati anche l’oggetto tokenDetails, che contiene tutte le informazioni relative al token generato, come mostrato nell'esempio di seguito, dove:

  • TokenValue: rappresenta il token associato alla carta. Può essere utilizzato per eseguire transazioni future senza richiedere nuovamente i dati al buyer.
  • CardDetails: contiene informazioni relative alla carta tokenizzata (ultime cifre, mese e anno di scadenza), utili per mostrare al buyer i dettagli della carta.
  • CardAssets: include eventuali risorse grafiche associate alla carta.

Request

GET /api/v1/payment/detail/{{PaymentID}}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "detail",
        //...
        "tokenDetails": {
            "TokenValue": "40ZUU8NXALR33101",
            "TokenExpiryMonth": "05",
            "TokenExpiryYear": "27",
            "TokenProvider": "AXERVE",
            "CardDetails": {
                "CardSuffix": "3101",
                "CardExpiryMonth": "05",
                "CardExpiryYear": "27",
                "CardHolderName": null
            },
            "CardAssets": {
                "CardArt": {
                    "Type": null,
                    "MediaContents": null,
                    "Height": null,
                    "Width": null
                },
                "BrandLogo": {
                    "Type": null,
                    "MediaContents": null,
                    "Height": null,
                    "Width": null
                }
            }
        },
        //...
    }
}
Mostrare i dati della carta al buyer

Per mostrare al buyer il finale del numero di carta è possibile utilizzare il campo CardSuffix, che rappresenta le ultime quattro cifre della carta tokenizzata. Se necessario, è possibile mostrare anche il mese e l’anno di scadenza utilizzando i campi CardExpiryMonth e CardExpiryYear, presenti nell’oggetto CardDetails. Questi dati permettono di identificare la carta associata al token senza esporre informazioni sensibili.

Aggiornamento Token​

L'aggiornamento di un token è possibile solo per la tipologia di token proprietari, i token di circuito vengono aggiornati automaticamente dai circuiti e non richiedono gestione manuale da parte dell’esercente.

Per aggiornare un token proprietario è disponibile la chiamata POST shop/token.

Nella richiesta è necessario indicare:

  • il token associato alla carta;
  • il mese e l’anno di scadenza aggiornati.

I dati aggiornati della carta devono essere richiesti al buyer.

Questa operazione consente di mantenere il token valido per utilizzi futuri, garantendo la continuità dei pagamenti ricorrenti o successivi senza dover richiedere nuovamente l’inserimento del numero di carta.

Request

POST /api/v1/shop/token
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{  
  "shopLogin":"GESPAY12345",
  "creditCard": {
    "token": "{token}",
    "expMonth": "{newMonth}", //mese di scadenza aggiornato
    "expYear": "{newYear}" //anno di scadenza aggiornato
  }
}

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "UPDATETOKEN",
        "transactionResult": "OK"
    }
}

Cancellazione Token​

Per richiedere la cancellazione di un token, è possibile utilizzare la chiamata DELETE shop/token passando all’interno del percorso dell’URL i parametri necessari, shopLogin e il token da cancellare.

La stessa chiamata può essere utilizzata anche per la cancellazione dei token generati tramite metodi di pagamento alternativi (APM), se supportato dal servizio.

Request

DELETE api/v1//shop/token/{shopLogin}/{token}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "result": "OK",
        "token": "{token}"
    }
}
Cancellazione

La cancellazione di un token è un’operazione irreversibile.
Una volta eliminato, il token non potrà più essere utilizzato per future transazioni o aggiornamenti.

Gruppi Token​

Fabrick offre la possibilità di creare gruppi token, pensati per i merchant che gestiscono più shop con la stessa partita IVA o ragione sociale. Ogni shopLogin che ne fa parte mette a disposizione del gruppo i token generati e può a sua volta utilizzare quelli degli altri, evitando di richiedere nuovamente al buyer l'inserimento dei dati della carta.

Token condivisi

All'interno di un gruppo token è possibile condividere esclusivamente i token carta. I token generati dagli APM non sono condivisibili e restano utilizzabili solo dallo shopLogin che li ha generati.

Richiesta del servizio

I gruppi token vengono configurati su richiesta. Per attivare il servizio contatta il tuo referente commerciale o l'assistenza tramite questo link.