Comprendere il flusso di pagamento e i requisiti
Se vuoi scoprire come accettare pagamenti in criptovaluta su un sito Next.js, parti dal flusso, non dal codice. In genere, un pagamento in criptovaluta si articola in 4 fasi: creare un ordine, mostrare una richiesta di pagamento, monitorare la blockchain e contrassegnare l’ordine come pagato solo dopo aver verificato la transazione. Capire come accettare pagamenti in criptovaluta con Next.js significa progettare con attenzione ciascuna di queste fasi.
Sembra semplice. Ma raramente lo è.
“Accettare criptovalute” su un sito Next.js non significa che la tua app debba custodire le monete. Nella maggior parte dei casi, il sito crea una richiesta di pagamento per il cliente, che invia i fondi dal proprio wallet; poi un servizio di pagamento o il tuo backend conferma il trasferimento. Un buon checkout prevede anche una scadenza, perché un importo corretto alle 10:00 potrebbe non esserlo più 20 minuti dopo.
Devi anche decidere quali reti e asset supportare. Un negozio che accetta USDT su Ethereum, Polygon e BNB Chain non svolge lo stesso compito di un sito che accetta solo BTC su un’unica blockchain. La scelta della rete influisce sulle commissioni, sui tempi di conferma e sul tipo di wallet di cui ha bisogno il cliente. Se accetti pagamenti sulla rete sbagliata, i fondi potrebbero finire in un posto in cui non riuscirai ad associarli a un ordine.
Ecco una verifica pratica: un cliente alla prima esperienza riesce a completare il checkout in meno di 2 minuti? Se la risposta è no, il flusso va migliorato. Un wallet, un importo, un indirizzo ben visibile e una pagina di stato chiara. È questo il livello di chiarezza che le persone si aspettano.
Scegliere un provider di pagamento in criptovaluta o un’integrazione con un wallet
Esistono 3 approcci principali per creare un checkout in criptovaluta. Il primo è un checkout ospitato da un provider. Il secondo è un’integrazione diretta con un wallet, in cui l’app comunica con una libreria per wallet. Il terzo è un gateway di pagamento che fa da tramite tra l’utente e la blockchain. Ogni opzione comporta un impegno diverso in fase di configurazione; quella giusta dipende dal fatto che tu dia la priorità alla velocità, al controllo o a entrambi. Se ti stai chiedendo come integrare un gateway di pagamento crypto in Next.js, valuta in particolare il supporto per la creazione di fatture, il monitoraggio delle conferme e l’invio di webhook.
Un checkout ospitato è in genere la soluzione più rapida da implementare. Crei una fattura, reindirizzi il cliente a una pagina ospitata e il provider si occupa di rilevare il pagamento. Un’integrazione diretta con un wallet può integrarsi meglio nel prodotto, ma di solito richiede più codice, comporta più casi particolari e ti assegna maggiori responsabilità nella conferma dei pagamenti. Un gateway fa da intermediario e spesso è la scelta più pratica per l’e-commerce, perché può creare fatture, monitorare le conferme e inviare webhook.
Prima di scegliere, verifica 5 aspetti: le monete supportate, le blockchain supportate, il supporto per i webhook, la scadenza delle fatture e la quantità di codice backend che dovrai scrivere. Se stai valutando le opzioni per un negozio, la guida ai gateway di pagamento in criptovaluta per l’e-commerce è un buon punto di partenza: affronta la stessa scelta dal punto di vista di chi vende. Un freelance che fattura ai clienti potrebbe dare più importanza a fatture e link di pagamento che a una vetrina online: ecco perché conta anche la prospettiva dei gateway di pagamento in criptovaluta per freelance.
Una precisazione: se un provider dichiara di supportare “tutti i principali asset”, chiedi l’elenco preciso. “Tutti” è vago. “BTC, ETH e USDC su 3 reti” è un’informazione su cui puoi basare una decisione concreta.
Configurare il progetto Next.js per i pagamenti
Parti da una struttura dell’app pulita. In un progetto Next.js con App Router, inserisci la logica di pagamento nelle route o nelle server action e tieni le chiavi segrete lontane dal client. Una struttura semplice potrebbe prevedere 1 pagina prodotto, 1 modulo di checkout, 1 route API per creare le fatture e 1 route webhook per gli eventi di pagamento.
Le variabili d’ambiente dovrebbero includere la chiave segreta del provider di pagamento, il segreto del webhook e i valori API pubblici che possono essere esposti nel browser. Non inserire la chiave segreta in un componente client: un errore del genere può compromettere l’intero account e le conseguenze possono diventare costose molto in fretta.
Se il provider offre un SDK, installalo solo nel livello server. Se invece mette a disposizione endpoint HTTP standard, vanno bene anche quelli. Il principio non cambia: il browser chiede al backend Next.js di creare una richiesta di pagamento e il backend comunica con il provider. Non deve essere il browser a decidere che un ordine è stato pagato.
Per i team che passano dai pagamenti con carta, la struttura non è molto diversa da un flusso Stripe: cambiano solo le fasi di verifica. Se il confronto ti è utile, leggi come migrare da Stripe prima di definire le route API. Per un prototipo basta una route API; quando aggiungi tentativi, rimborsi e cronologia degli stati dell’ordine, potrebbero servirne 3 o 4.
Creare l’interfaccia di checkout in Next.js
L’interfaccia di checkout può essere una scheda prodotto, una pagina del carrello o un semplice pulsante che avvia il pagamento. In un componente client di Next.js, di solito il pulsante invia i dettagli dell’ordine alla route server, attende una risposta e poi reindirizza il cliente oppure mostra le istruzioni per il wallet.
Mantieni il modulo breve. Spesso bastano il nome del prodotto, l’importo, l’indirizzo e-mail e, magari, una nota sull’ordine. Se chiedi 9 informazioni, aspettati più abbandoni. Se ne chiedi 3, gli utenti completano il checkout più in fretta. Un checkout da 30 secondi è preferibile a uno da 3 minuti, anche se entrambi portano allo stesso pagamento.
Il testo del pulsante di pagamento deve essere esplicito: “Paga in criptovaluta”, non “Continua” o “Procedi”. Queste etichette non chiariscono cosa comporti il passaggio successivo. Quando l’utente fa clic, contatta il backend, recupera la richiesta di pagamento e mostra nella stessa schermata l’indirizzo del wallet, il codice QR e l’importo.
Una soluzione utile è lasciare visibile il riepilogo dell’ordine mentre si caricano le istruzioni di pagamento. In questo modo, il cliente vede insieme il prodotto esatto e l’importo esatto. Si riduce così il rischio di confusione quando il prezzo è fisso in USD, ma il pagamento avviene in un asset volatile.
Generare indirizzi di pagamento, fatture o link di pagamento
Ogni ordine dovrebbe corrispondere a 1 richiesta di pagamento univoca. Può trattarsi di un indirizzo wallet, di un link di pagamento o di una fattura creata dal provider. Riutilizzare lo stesso indirizzo per ogni cliente complica la riconciliazione e può generare richieste di assistenza evitabili.
Per un piccolo negozio, potresti generare un nuovo indirizzo per ogni ordine e salvare nel database l’indirizzo, l’importo previsto, l’asset e la scadenza. In un flusso basato su un provider, invece, potresti ricevere dal provider un ID fattura e un link di pagamento ospitato. In entrambi i casi, associa la richiesta di pagamento all’ID dell’ordine prima di mostrarla al cliente.
Mostra i dettagli in modo semplice: asset, rete, importo e destinazione. Un codice QR è utile, ma non deve sostituire il testo. Alcuni wallet leggono male i codici QR, mentre altri utenti preferiscono copiare e incollare i dati. Un indirizzo ben visibile resta comunque la soluzione di sicurezza.
Se devi supportare pagamenti tramite indirizzo per servizi o fatture, i principi sono simili a quelli descritti nell’articolo sui gateway di pagamento in criptovaluta per freelance. Per un acquisto occasionale, spesso è più pratico un link di pagamento; se invece ti servono la cronologia dei pagamenti e i promemoria, è meglio creare una fattura dedicata.
Confermare i pagamenti sulla blockchain e aggiornare lo stato dell’ordine
È nella fase di conferma dei pagamenti che molti team diventano superficiali. Non contrassegnare un ordine come pagato solo perché un wallet mostra un trasferimento in sospeso. Non fidarti del solo browser. Il backend deve verificare la transazione controllando direttamente la blockchain o ricevendo un webhook firmato dal provider di pagamento.
Il flusso abituale è semplice. Il provider rileva il pagamento, invia un webhook alla route Next.js e il server verifica la firma prima di aggiornare lo stato dell’ordine. Se implementi questo passaggio autonomamente, devi verificare l’hash della transazione, l’indirizzo di destinazione, l’asset, l’importo e il numero di conferme richiesto dalla tua policy. Un pagamento può sembrare valido prima di essere definitivo. Questo è un passaggio fondamentale per come creare un checkout crypto con webhook: la notifica deve essere verificata prima di modificare lo stato dell’ordine.
Usa un modello di ordine con 3 stati: in attesa, confermato e pagato. “In attesa” significa che la richiesta esiste. “Confermato” significa che la blockchain ha rilevato il pagamento e che la transazione ha ricevuto conferme sufficienti. “Pagato” significa che l’app ha aggiornato l’evasione dell’ordine o il controllo degli accessi. Mantieni separati questi stati: così il team di assistenza può capire se il cliente sta aspettando, se il pagamento è stato verificato o se l’ordine è già stato consegnato.
Se usi i webhook, convalidali ogni volta. L’articolo su come verificare i webhook firmati di Payora è utile anche se non usi PHP, perché il principio è lo stesso: rifiutare i messaggi che non dimostrano di provenire dal provider. Questa singola verifica può bloccare sul nascere i falsi eventi di pagamento.
Gestire i casi particolari, la sicurezza e i test
Il checkout in criptovaluta può non andare a buon fine in più modi rispetto a un pagamento con carta. Una quotazione può scadere. Un cliente può inviare fondi sulla rete sbagliata. Un wallet può inviare un importo leggermente inferiore. Il browser può aggiornarsi a metà procedura. Per ciascun caso serve una risposta che indichi all’utente un passaggio successivo preciso.
Le quotazioni scadute non devono restare in sospeso. Se un link di pagamento è valido per 15 minuti, mostra chiaramente il conto alla rovescia e crea una nuova richiesta alla scadenza. Per i trasferimenti sulla rete sbagliata serve un canale di assistenza, perché i fondi potrebbero esistere, ma non trovarsi dove se li aspetta l’app. Puoi accettare i pagamenti inferiori all’importo previsto, rifiutarli o segnalarli per una verifica, ma la policy va definita prima del lancio, non dopo il primo reclamo.
La sicurezza non è facoltativa. Conserva le chiavi segrete solo in variabili d’ambiente accessibili al server. Verifica le firme dei webhook. Archivia solo i dati di pagamento indispensabili. Se registri gli ID delle transazioni, maschera qualsiasi informazione sensibile non necessaria per il debug. Prima di accettare pagamenti reali, esegui i test su una testnet o con gli strumenti sandbox del provider. Per una lista di controllo pratica, consulta come testare un pagamento in criptovaluta prima di collegare un wallet reale.
Non dimenticare gli eventi duplicati. Alcuni provider inviano di nuovo i webhook e, se non presti attenzione, la stessa transazione può comparire più volte nel tuo sistema. Il codice che aggiorna l’ordine deve essere idempotente: lo stesso evento non deve contrassegnare lo stesso ordine come pagato più di una volta. Questa singola precauzione fa risparmiare ore di lavoro.
Pubblicare, monitorare e migliorare l’esperienza di checkout
La distribuzione su Vercel o su un servizio di hosting simile di solito funziona bene con Next.js, ma le parti relative ai pagamenti richiedono comunque attenzione. Verifica che l’endpoint webhook sia raggiungibile pubblicamente, che le variabili d’ambiente siano configurate in produzione e che la build non dipenda da valori disponibili solo in locale. Una route di pagamento che funziona sul tuo computer ma non in produzione è un errore classico.
La registrazione dei log è importante. Registra la creazione delle fatture, la ricezione dei webhook, gli esiti delle verifiche e le modifiche di stato. Raccogli dettagli sufficienti per seguire un singolo ordine dall’inizio alla fine, ma non inserire segreti nei log. Se un cliente dice di aver pagato alle 14:32, dovresti riuscire a trovare l’evento corrispondente in pochi secondi, non in poche ore.
Piccoli miglioramenti all’esperienza utente possono ridurre gli ostacoli più di quanto ci si aspetti. Mostra l’importo due volte: nel riepilogo dell’ordine e nella fase di pagamento. Mantieni visibile il pulsante di pagamento dopo il caricamento della fattura. Aggiungi un pulsante per copiare l’indirizzo. Spiega chiaramente la fase di conferma, perché spesso gli utenti aggiornano la pagina mentre aspettano. Se la pagina non mostra nulla, un aggiornamento ogni 5 secondi può sembrare un’attesa di 5 minuti.
A questo punto, la vera sfida non è il primo pagamento. Sono il secondo, il terzo e quello che si blocca nel passaggio tra un wallet, una blockchain e il backend Next.js. Se il tuo sistema gestisce correttamente questi 3 casi, hai un checkout di cui i clienti possono fidarsi.
Comments