--- title: "Non-Payment Authentication (NPA)" description: "Autentica il titolare della carta con 3D Secure 2 e salva i dati senza addebiti: il risultato è un token autenticato per pagamenti ricorrenti o one-click." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/exemptions-exceptions-3ds/npa/" language: "it" --- # Non-Payment Authentication (NPA) La **Non-Payment Authentication (NPA)** è un flusso di autenticazione **3D Secure 2** ([3DS2](https://www.emvco.com/emv-technologies/3-d-secure/)) che consente al merchant di **verificare il titolare della carta e salvare i dati senza effettuare alcun addebito**. A differenza di un pagamento tradizionale, in cui l’autenticazione 3DS e la transazione finanziaria avvengono contestualmente, con NPA il processo si limita alla sola fase di autenticazione.\ Il risultato è un **token di carta autenticato** che è possibile utilizzare per successive transazioni (ad esempio pagamenti ricorrenti o one‑click). ![Non-Payment Authentication](https://docs.fabrick.com/assets/images/npa-toast-1a6b4f70f2f8c3f64e734e1aca647aee.png) > **Quando usare NPA** > > NPA è indicato nei seguenti scenari: > > - **Tokenizzazione della carta** in fase di registrazione, prima di un acquisto > - **Verifica del titolare della carta** senza richiedere un pagamento > **NPA non addebita importi** > > Il flusso NPA non genera alcun movimento finanziario.\ > Per effettuare un pagamento è necessario avviare una nuova transazione. --- ## Configurazione backoffice Per ricevere i dettagli dell’autenticazione 3DS al termine della transazione, è necessario abilitare il campo **`ThreeDS`** nel backoffice Gestpay.\ In assenza di questa configurazione, le transazioni NPA funzioneranno correttamente ma **non restituiranno le informazioni 3DS**. Percorso di configurazione: **Pagina Pagamento → Campi & Parametri → ThreeDS** Impostazioni disponibili: - **No Display** → integrazioni che **non** utilizzano la pagina di pagamento Fabrick - **Payment Page** → integrazioni che utilizzano la **pagina di pagamento Fabrick** ![Non-Payment Authentication](https://docs.fabrick.com/assets/images/token-backoffice-gestpay-01-c028d47c11e5faeae4b5107af2ab8832.png) Per tutte e due le configurazioni è necessario abilitare il campo **threeDS** nella sezione **Campi & Parametri**. --- ## Flusso di integrazione Il flusso NPA è supportato da tutte le [tipologie di integrazione](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/) offerte da Fabrick. ### Integrazioni supportate ✓ — Checkout Page ✓ — Pay By Link ✓ — Lightbox ✓ — Web Component ✓ — API Only --- ## Inizializzazione della richiesta NPA Per avviare un flusso NPA è necessario effettuare, lato server, una chiamata **`payment/create`** impostando i seguenti parametri: - **`amount`** con importo *`0`* per non addebitare nessun importo. - **`transDetails.type`** con *`NPA`* per indicare al sistema di processare la transazione come sola autenticazione - **`paymentType`** con *`["CREDITCARD"]`* per indicare al sistema di presentare solo il form carta sulla pagina di pagamento. - **`requestToken`** valorizzato con *`MASKEDPAN`*. > **pagina di pagamento** > > Il parametro **paymentType** non è necessario nelle integrazioni **API Only**, dove il form carta è gestito direttamente dal merchant. > **token** > > Il parametro **requestToken** consente di ottenere un token della carta autenticata da utilizzare per transazioni future.\ > Vedi [**Tokenizzazione**](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/). **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", //nessun addebito "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["CREDITCARD"], //presentare pagina di inserimento dati carta "requestToken": "MASKEDPAN", //richiesta token della carta "transDetails": { "type": "NPA" //transazione di sola autenticazione } } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "d3026f8c-88e3-4862-a962-c0fa29e0f266", "paymentID": "2423879934511", "userRedirect": null, "qrCode": null } } ``` --- ## Processo autenticazione 3DS Per tutte le **integrazioni hosted**, la fase di autenticazione è gestita direttamente da Fabrick. Nelle **integrazioni API Only** il merchant deve gestire manualmente la fase di autenticazione effettuando il redirect del buyer verso l’URL restituito dopo l’invio dei dati carta. Dopo l’invio dei dati carta, il sistema restituisce l’errore **8006** nel campo `payload.transactionErrorCode`, che indica la necessità di completare l’autenticazione del buyer. L’URL di autenticazione è disponibile nel campo `payload.userRedirect.href`. ## Dettaglio transazione Al termine del flusso, Fabrick restituisce l’esito dell’autenticazione e il token della carta. > Per maggiori dettagli consulta la sezione **Dettaglio transazione e Notifica del Pagamento** della specifica integrazione utilizzata Per verificare il dettaglio completo dell’autenticazione è possibile utilizzare l’endpoint **`GET payment/detail`**, passando il `paymentID`. **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", "transactionResult": "AUTHENTICATED", "transactionState": "", "transactionErrorCode": "", "transactionErrorDescription": "", "bankTransactionID": "1318", "shopTransactionID": "", "shopTransactionID_2": "", "authorizationCode": "", "paymentID": "", "currency": "", "country": "", "company": "", "tdLevel": "", "threeDS": { "authenticationResult": { "authenticationLevel": "2C", "authenticationStatus": "Y", "authStatusReason": "", "challengeResultTransStatus": "", "XID": "87dc52d7-a059-4afa-8763-bf4a86e3ede9", "AV": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=", "ECI": "05", "AVAlgorithm": "", "threeDsVersion": "2.1.0" }, "transDetails": { "authData": "", "authMethod": "02", "authTimeStamp": "202504281041", "acsID": "bc7007fe-45fc-471d-999e-d6111951999e" } }, "events": null, "buyer": null, "risk": null, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "", "dcc": null, "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "40G5KMXUQQ613101", "tokenExpiryMonth": "05", "tokenExpiryYear": "27", "tokenDetails": { "TokenValue": "40G5KMXUQQ613101", "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 } } }, "fraudPrevention": null, "automaticOperation": null } } ``` Nella risposta, i campi rilevanti per un flusso NPA sono: | Campo | Descrizione | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `transactionResult` | Esito dell'autenticazione: `AUTHENTICATED` / `DECLINED` | | `threeDS.authenticationResult.authenticationLevel` | Livello di autenticazione 3DS | | `threeDS.authenticationResult.authenticationStatus` | Stato dell’autenticazione | | `threeDS.authenticationResult.authStatusReason` | Codice motivo dell’esito | | `threeDS.authenticationResult.ECI` | [Electronic Commerce Indicator](https://docs.midtrans.com/docs/what-is-eci-on-3ds-protocol), valorizzato solo in caso di esito positivo | | `token` | Token della carta | | `tokenExpiryMonth` / `tokenExpiryYear` | Scadenza del token | > **Dettagli del token** > > Per maggiori informazioni sul token è possibile leggere l'oggetto `tokenDetails`, che riporta lo stesso valore nel campo `TokenValue` insieme ai dati della carta tokenizzata e alla tipologia del token (`TokenProvider`). Vedi [Lettura Dati Token](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/#lettura-dati-token). > **Gestione esiti negativi in NPA** > > Le transazioni NPA con esito negativo riportano `transactionResult: "DECLINED"` e valorizzano il dettaglio dell’errore nei campi `authenticationStatus` e `authStatusReason`. --- ## Dettaglio autenticazione e gestione errori ### authenticationLevel Il campo `authenticationLevel` indica il tipo di flusso di autenticazione 3DS applicato alla transazione | Valore | Descrizione | | ------ | -------------------------------------------------------------------------------------- | | `1H` | **3DS 1.0 half** — Autenticazione 3DS 1.0 parziale. | | `1F` | **3DS 1.0 full** — Autenticazione 3DS 1.0 completa. | | `2F` | **3DS 2.0 frictionless** — Autenticazione 3DS 2.0 senza interazione del buyer. | | `2C` | **3DS 2.0 challenge** — Autenticazione 3DS 2.0 con challenge completata dal buyer. | | `2E` | **3DS 2.0 exemption** — Autenticazione 3DS 2.0 con esenzione applicata. | | `OL` | **One leg** — Transazione processata come one leg, autenticazione non richiesta. | | `TR` | **TRA esterna** — Transazione processata come TRA (Transaction Risk Analysis) esterna. | | `NA` | **No authentication** — Nessuna autenticazione eseguita. | ### authenticationStatus Il campo `authenticationStatus` indica l’esito dell’autenticazione. | Valore | Descrizione | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Y` | **Frictionless** — *l’issuer ha autenticato* con successo il buyer *senza richiedere alcuna interazione esplicita*. L’autenticazione è considerata completata positivamente e la transazione può proseguire. | | `C` | **Challenge** — *l’issuer richiede la verifica del buyer*. Il buyer deve completare l’autenticazione tramite la challenge, utilizzando l’URL fornito nel campo `payload.userRedirect.href`. L’esito della transazione dipenderà dal risultato della challenge. | | `N` | **Not Authenticated** — *l’issuer decide di non concedere l’autenticazione del buyer* sulla base delle proprie valutazioni di rischio. In questo scenario *la fase di challenge non viene avviata*, in quanto l’autenticazione non è autorizzata dall’issuer. *La transazione termina quindi con esito negativo*. | | `U` | **Authentication Could Not Be Performed** — l’autenticazione non può essere eseguita a causa di un errore tecnico presso il *Directory Server (DS)* o *l’Access Control Server (ACS)*. Dal punto di vista del flusso transazionale, l’esito viene *gestito come `N`*. | | `A` | **Attempted to Authenticate** — l’autenticazione è stata *tentata*, ma non completata (ad esempio per limiti tecnici o di canale), pur *consentendo di procedere*. L’esito viene trattato come `Y` ai fini del flusso e della liability. | | `R` | **Rejected** — *l’issuer rifiuta esplicitamente la richiesta di autenticazione*. L’autenticazione non viene completata e l’esito è *gestito come `N`*, con conseguente esito negativo della transazione. | ### authStatusReason Il campo `authStatusReason` specifica il motivo dell’esito restituito dall’issuer o dall’ACS. In caso di `authenticationStatus: N` o `U`, questo campo fornisce un codice numerico che identifica la causa specifica del rifiuto o dell’impossibilità di autenticare. | Codice | Descrizione | | ------- | ---------------------------------------------------------------------------------- | | `01` | Card authentication failed | | `02` | Unknown Device | | `03` | Unsupported Device | | `04` | Exceeds authentication frequency limit | | `05` | Expired card | | `06` | Invalid card number | | `07` | Invalid transaction | | `08` | No Card record | | `09` | Security failure | | `10` | Stolen card | | `11` | Suspected fraud | | `12` | Transaction not permitted to cardholder | | `13` | Cardholder not enrolled in service | | `14` | Transaction timed out at the ACS | | `15` | Low confidence | | `16` | Medium confidence | | `17` | High confidence | | `18` | Very High confidence | | `19` | Exceeds ACS maximum challenges | | `20` | Non-Payment transaction not supported | | `21` | 3RI transaction not supported | | `22` | ACS technical issue | | `23` | Decoupled Authentication required by ACS but not requested by 3DS Requestor | | `24` | 3DS Requestor Decoupled Max Expiry Time exceeded | | `25` | Decoupled Authentication was provided insufficient time to authenticate cardholder | | `26` | Authentication attempted but not performed by the cardholder | | `27` | Preferred authentication method not supported | | `28–79` | Riservati per uso futuro EMVCo (valori non validi fino a definizione EMVCo) | | `80–99` | Riservati per uso del Directory Server (DS) | Di seguito un esempio di risposta `payment/detail` con esito negativo **DECLINED**, in cui `transactionErrorCode` e `transactionErrorDescription` risultano vuoti e la causa dell'errore è leggibile tramite `authenticationStatus` e `authStatusReason`: **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", "transactionResult": "DECLINED", "transactionState": "", "transactionErrorCode": "", "transactionErrorDescription": "", "threeDS": { "authenticationResult": { "authenticationLevel": "2C", "authenticationStatus": "N", "authStatusReason": "19", "XID": "29797f4c-52c7-404e-8ce5-6e17d946e38d", "AV": "", "ECI": null, "threeDsVersion": "2.1.0" }, "transDetails": { "authMethod": "02", "authTimeStamp": "202504281129", "acsID": "96be2efb-3f2d-49c5-93f5-c8d7e9ec0107" } }, "token": "40G5KMXUQQ613101", "tokenExpiryMonth": "05", "tokenExpiryYear": "27" } } ``` In questo esempio `authenticationLevel: "2C"` indica che per la transazione è stato richiesto il flusso **3DS2 con challenge**, questo valore descrive il tipo di flusso e non l’esito dell’autenticazione. `authenticationStatus: "N"` indica che l’autenticazione è stata negata, mentre `authStatusReason: "19"` specifica la causa **"Exceeds ACS maximum challenges"** — il numero massimo di challenge consentiti dall’ACS è stato superato.