--- title: "Tokenizzazione" description: "Sostituisci i dati della carta con un token per pagamenti successivi e ricorrenti: tipologie di token proprietari e di circuito, richiesta con requestToken, lettura di payload.token e tokenDetails, aggiornamento, cancellazione e gruppi token." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/" language: "it" --- # 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/recurring-payments/) > **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](https://docs.fabrick.com/assets/images/token-toast-it-0f7bd2d80c71889c32fc609c0f5f5953.png) ![Tokenizzazione](https://docs.fabrick.com/assets/images/token-toast-2-it-136bf130137aad829cec93dedcb96d59.png) --- ## 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** > > - Token PSP e di circuito: [*strumenti strategici per l'Ecommerce*](https://www.axerve.com/approfondimenti/edu-content/token-psp-e-di-circuito-strumenti-strategici-per-ecommerce) > - Whitepaper Tokenizzazione: [*lo strumento strategico per gli Ecommerce PSD2 compliant*](https://www.axerve.com/approfondimenti/whitepaper/tokenization) --- ## 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](https://docs.fabrick.com/assets/images/token-backoffice-gestpay-01-c028d47c11e5faeae4b5107af2ab8832.png) 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`. - **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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/#lettura-dati-token). --- ### 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**](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/exemptions-exceptions-3ds/npa/). > **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** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/#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** ```http GET /api/v1/payment/detail/{{PaymentID}} Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "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** ```http POST /api/v1/shop/token Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin":"GESPAY12345", "creditCard": { "token": "40ZUU8NXALR33101", "expMonth": "08", //mese di scadenza aggiornato "expYear": "31" //anno di scadenza aggiornato } } ``` **Response** ```json { "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** ```http DELETE /api/v1//shop/token/{shopLogin}/{token} Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** ``` **Response** ```json { "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](https://landing.fabrick.com/fabrick-dashboard-support). ## Approfondimenti - [Migrazione — Migrazione di token carta e pagamenti ricorrenti da un altro PSP verso Fabrick, e da Fabrick verso un nuovo PSP.](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/migration/)