nexi_payment
Un plugin Flutter per i gateway di pagamento di Nexi: il checkout di Nexi su Android e iOS, e un esito di cui l’app si può fidare.
- Ruolo
- Autore e maintainer: l’API Dart, il codice Android (Java) e iOS (Swift), i test, la CI e i rilasci
- Tipo
- Plugin Flutter open source, licenza MIT, su pub.dev
- Periodo
- 2020 – oggi (2.3.0, luglio 2026)
- Piattaforme
- Android e iOS
Il prodotto
nexi_payment permette a un’app Flutter di ricevere pagamenti tramite Nexi. L’app passa l’ordine, il checkout di Nexi raccoglie i dati della carta (l’app non li vede mai) e l’app riceve indietro cosa è successo: pagato, annullato, oppure fallito, e perché.
L’ho scritto a giugno 2020, mentre integravo Nexi nell’app di Criluma Viaggi, e l’ho pubblicato su pub.dev. A luglio 2026 l’ho riscritto come 2.0: il nuovo gateway NPG di Nexi accanto al classico XPay, un unico contratto per gli errori su entrambe le piattaforme, test che pilotano gli SDK reali e correzioni per i momenti in cui gli SDK nativi di Nexi restano in silenzio o riportano la cosa sbagliata.
- 7
- rilasci stabili su pub.dev, dalla 1.0.0 di giugno 2020 alla 2.3.0 di luglio 2026
- 53
- dei 58 commit sono miei; gli altri sono arrivati come pull request di altri contributori
- 2
- gateway Nexi dietro un’unica API Dart: il classico XPay e NPG
- 49
- test automatici: 35 unit test e 14 test di integrazione che girano su un dispositivo
Tour guidato
L’app in azione
Scegli una registrazione, o salta direttamente a un capitolo.
Registrate su un emulatore Android da una build di release dell’app di esempio, con pagamenti nella sandbox pubblica di Nexi. I campi del checkout vengono individuati tramite DevTools e toccati come farebbe un dito; per funzionare, la pagina della sandbox ha bisogno di due piccole correzioni, applicate allo stesso modo.
Cosa fa
Da un pulsante nell’app a un esito di cui fidarsi
01
Una chiamata apre il checkout di Nexi
L’app passa l’ordine (id, importo, valuta, lingua) e il plugin apre la Hosted Payment Page di Nexi tramite l’SDK nativo: una carta, o uno degli altri metodi offerti da Nexi. La carta si digita sulla pagina di Nexi, mai nell’app.
02
Riepilogo e 3-D Secure
Nexi mostra il riepilogo con la carta mascherata, poi passa la mano alla banca del titolare per il 3-D Secure: nella sandbox è la DemoBank, a cui si può chiedere di far riuscire o fallire l’autenticazione.
03
Un esito di cui l’app si può fidare
Gli SDK nativi chiamano la loro callback “completed” per qualsiasi pagamento concluso, compresi quelli rifiutati. Il plugin segnala un successo solo per un’operazione finale EXECUTED o AUTHORIZED; un’autenticazione fallita torna come errore con il codice di Nexi. Prima della 2.0, su iOS un pagamento negato arrivava addirittura come semplice stringa; ora entrambe le piattaforme sollevano gli stessi errori con codice.
04
Ogni via d’uscita chiude la chiamata
Il tasto Indietro, il link di annullamento di Nexi, un pannello trascinato via su iOS: ognuno chiude il pagamento come annullato, e il pagamento successivo si apre normalmente. Due di queste uscite lasciavano l’app in attesa di una risposta che non arrivava mai.
Sotto il cofano
Come è stato realizzato
Colmare i silenzi degli SDK
XPaySDK chiude il suo checkout al tasto Indietro di Android senza richiamare l’app, e NPGSDK su iOS può lasciar chiudere il suo pannello senza dire una parola. Il plugin osserva il ciclo di vita del checkout e, se questo sparisce senza aver detto nulla, chiude con un annullamento (un esito reale ha sempre la precedenza), e una protezione rifiuta un secondo pagamento mentre ce n’è già uno aperto, invece di lasciare due chiamate in sospeso.
Quando l’SDK non sa leggere la propria risposta
NPGSDK 1.1.0 dichiara l’additionalData di un’operazione come una mappa di stringhe, ma il backend ci annida dentro un oggetto, così su Android l’SDK può non riuscire a interpretare l’esito di un pagamento andato a buon fine. Il plugin allora rilegge l’ordine dall’API degli ordini di NPG e riporta ciò che è successo davvero: non inventa mai un successo, e dice “esito sconosciuto” quando non può saperlo.
Pacchettizzazione, test e rilasci
Nexi non pubblica artefatti Maven e il suo pod iOS non ha una slice per il simulatore: gli SDK Android sono inclusi nel plugin, mentre i framework iOS vengono scaricati dai repository di release di Nexi al pod install e verificati con checksum SHA-256 fissati. Gli unit test blindano il contratto del canale, i test Patrol pilotano gli SDK reali sulla sandbox di Nexi, la CI esegue analisi, test e build a ogni push e pull request, e un tag di versione pubblica su pub.dev.
Registrare un plugin di pagamento
Un checkout vero, nella sandbox di Nexi.
Un plugin non ha schermate proprie, quindi le registrazioni mostrano la sua app di esempio (una build di release su un emulatore Android) che paga davvero nella sandbox pubblica di Nexi.
- 1
Il codice pubblicato, compilato in release
Il repository al tag 2.3.0, l’app di esempio compilata in modalità release con le credenziali della sandbox pubblicate da Nexi, installata su un emulatore. Nessuna chiave privata: i pulsanti del classico XPay richiedono un terminale di test dell’esercente e non sono mostrati.
- 2
Dentro la pagina di Nexi con DevTools
Il checkout è una pagina web dentro la WebView dell’SDK. Lo script di registrazione ne trova i campi tramite Chrome DevTools, che indica anche dove si trova la WebView sullo schermo, e li tocca sul touchscreen dell’emulatore come farebbe un dito, digitando la carta di test di Nexi.
- 3
Due stranezze della sandbox
La pagina della sandbox a volte lascia senza etichetta il pulsante della carta, e non abilita mai il pulsante di pagamento per una carta digitata a mano. Lo script corregge entrambe le cose da DevTools, la seconda esattamente come fa il runbook per i test su dispositivo del plugin stesso.
- 4
Tre finali
Un pagamento che va a buon fine, uno in cui il 3-D Secure fallisce e due modi di andarsene. Ogni ripresa parte da un’app azzerata e da un nuovo ordine.
Le pagine di pagamento, l’esercente della sandbox (WWW.CHARTA.IT) e la DemoBank fanno parte della sandbox pubblica di Nexi. La carta è la carta di test pubblicata da Nexi; il titolare è inventato.
Qui non c’è niente da provare: il plugin gira all’interno di app Android e iOS. Lo trovi su pub.dev e GitHub.
Ogni schermata
La raccolta completa degli screenshot
L’app di esempioEntrambi i gateway, il salvataggio della carta e un addebito ricorrente, un pulsante ciascuno. Hosted Payment PageLa pagina di Nexi, aperta dall’SDK nativo: carta o un altro metodo. La cartaLa carta di test pubblicata da Nexi; l’app non vede mai il numero. RiepilogoEsercente, importo, ordine e la carta mascherata. 3-D SecureLa DemoBank della sandbox chiede conferma al titolare della carta. EseguitoIl plugin segnala un successo solo per un pagamento eseguito o autorizzato. FallitoTHREEDS_FAILED, non un successo: il plugin controlla l’operazione finale. AnnullatoTasto Indietro: il plugin trasforma il silenzio dell’SDK in un annullamento. Uscire dalla paginaL’annullamento di Nexi chiede una conferma.
Prossimo caso di studio
Referi →