Passa al contenuto principale

Tokenizzazione

Visualizza come Markdown

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 il token e i relativi dettagli.
Questa configurazione è necessaria per ottenere i dati del token 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.

Seleziona la configurazione in base al tipo di integrazione:

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

Backoffice Gestpay - selezione della configurazione

Per entrambe le configurazioni, nella sezione Campi & Parametri abilita i seguenti campi:

  • Campi del token: restituiscono in risposta il token e la sua scadenza nei campi payload.token, payload.tokenExpiryMonth e payload.tokenExpiryYear.

    Backoffice Gestpay - campi token, mese e anno di scadenza

  • TokenDetails: restituisce in risposta l'oggetto payload.tokenDetails, che contiene maggiori dettagli sul token (tipologia, dati della carta tokenizzata e risorse grafiche associate). Vedi Lettura Dati Token.

    Backoffice Gestpay - campo TokenDetails

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)

Per i token carta e wallet, nelle risposte di payment/detail e payment/submit il token è restituito nel campo payload.token, insieme alla scadenza nei campi payload.tokenExpiryMonth e payload.tokenExpiryYear. È questo il valore da salvare e da utilizzare nelle transazioni successive.

Per maggiori informazioni sul token è possibile leggere l’oggetto payload.tokenDetails, che riporta lo stesso valore nel campo TokenValue insieme ai dati della carta tokenizzata. Nel seguente esempio la chiamata payment/detail interroga una transazione completata per la quale era stato richiesto il token della carta:

  • TokenValue: il token associato alla carta, uguale al valore di payload.token. Può essere utilizzato per eseguire transazioni future senza richiedere nuovamente i dati al buyer.
  • TokenProvider: indica chi ha generato il token e quindi la sua tipologia. Con AXERVE si tratta di un token proprietario, generato da Fabrick; con VISA o MASTERCARD si tratta di un token di circuito, i cui dati vengono aggiornati automaticamente dal circuito (vedi Tipologie di Token).
  • 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",
        //...
        "token": "40ZUU8NXALR33101",
        "tokenExpiryMonth": "05",
        "tokenExpiryYear": "27",
        "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 verificare la tipologia del token è possibile leggere il campo tokenDetails.TokenProvider: l’aggiornamento è necessario solo con il valore AXERVE.

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": "40ZUU8NXALR33101",
    "expMonth": "08", //mese di scadenza aggiornato
    "expYear": "31" //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": "40ZUU8NXALR33101"
    }
}
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.

Approfondimenti​