Integrare i pagamenti Ethereum: guida per sviluppatori

L’integrazione dei pagamenti Ethereum consiste nell’accettare ETH o token nella Sua applicazione: assegnare a ogni cliente un indirizzo unico, rilevare la transazione quando arriva, decidere quando è definitiva e riconciliarla con l’ordine. Può essere costruita su nodi e JSON-RPC, oppure affidata a un’API che gestisce wallet e notifiche.

Questa guida copre entrambe le strade, così Lei può scegliere con i compromessi davanti agli occhi.

TL;DR

• Un pagamento Ethereum è una transazione firmata che sposta ETH o token. Inviarla non equivale a confermarla: va verificata la ricevuta.
• Decida prima: solo ETH, stablecoin e token ERC-20, oppure un token proprio. Questa scelta determina la gestione degli eventi e la strategia del gas.
• Usi un indirizzo di deposito per ordine o per utente, e ascolti gli eventi tramite webhook invece di fare polling.
• Consideri chiavi private, firme dei webhook e codice dei contratti come le tre superfici di sicurezza principali.
• Un’API come Chaingateway sostituisce il nodo e lo scanner dei blocchi, con piani da 49 € al mese. Le impostazioni del gas e la politica di conferma restano decisioni Sue.

Che cos’è un pagamento Ethereum?

Un pagamento Ethereum è un’istruzione firmata crittograficamente da un account, che aggiorna lo stato della rete, per esempio trasferendo ETH o token. Secondo la documentazione sulle transazioni di ethereum.org, un validatore controlla poi la transazione e la include in un blocco. Solo dopo questo passaggio il denaro esiste davvero all’indirizzo del destinatario.

Per la Sua applicazione questo ha una conseguenza pratica. Il cliente non paga Lei. Trasmette una transazione alla rete, e il Suo sistema deve accorgersene. Ogni elemento di un’integrazione è una variazione di questo problema di osservazione.

Ci sono due tipi di pagamento che incontrerà:

1. Trasferimenti di ETH nativo. La transazione stessa porta un destinatario e un valore. È semplice, e visibile direttamente nella transazione e nella sua ricevuta.
2. Trasferimenti di token (ERC-20 e simili). La transazione va al contratto del token, che aggiorna internamente i saldi. Lo standard definisce per questo un evento Transfer, come descritto nella specifica ERC-20 su ethereum.org. Il Suo sistema viene a sapere del pagamento da quel log di eventi, non dal campo valore della transazione.

La maggior parte dei checkout in stablecoin è del secondo tipo. Se controlla solo l’arrivo di ETH a un indirizzo, ne perderà molti.

Che cosa deve decidere prima di scrivere codice?

Quali asset accetterà?

Parta dal gruppo più ristretto che serve i Suoi clienti. Solo ETH è il più facile da implementare. Aggiungere una stablecoin elimina la volatilità dei prezzi, il che conta per fatture e abbonamenti. Se emette un token proprio, deve conoscerne anche i decimali, l’indirizzo del contratto e se si comporta come un ERC-20 standard.

Ogni asset in più aggiunge un indirizzo di contratto da monitorare, un valore di decimali da applicare e una regola di prezzo. Mantenga una piccola allowlist e rifiuti deliberatamente tutto il resto.

Checkout ospitato, link di pagamento o API?

Esistono tre forme di integrazione, che scambiano controllo con velocità:

Approccio	Adatto per	Cosa controlla Lei	A cosa rinuncia
Checkout ospitato o link di pagamento	Lancio rapido, volumi bassi	Quasi nulla del flusso	Branding, custodia, logica personalizzata
Connessione wallet nel proprio front end	Dapp in cui gli utenti hanno già ETH	L’esperienza utente	Rilevamento e riconciliazione restano a carico Suo
API backend con wallet e webhook	App, marketplace, fatturazione SaaS	Indirizzi, importi, logica degli ordini	Gestione di una propria infrastruttura

Se è uno sviluppatore che integra i pagamenti in un prodotto, l’ultima riga è di solito quella a cui arriva. Una lista utile per qualsiasi provider: offre una sandbox, formati di errore chiari, limiti di frequenza documentati e webhook compatibili con il Suo stack?

Custodia e conformità

Chi detiene le chiavi? Se la Sua piattaforma genera wallet di deposito per i clienti, Lei gestisce fondi, e a seconda della giurisdizione e del modello di business ciò può comportare obblighi di licenza o di segnalazione. Chieda a un avvocato che conosca il Suo mercato prima del lancio, non dopo. Questa guida tratta l’ingegneria, non la consulenza legale.

Come funziona il flusso di pagamento, passo dopo passo?

Ecco la sequenza che regge in produzione, che la costruisca Lei o che la acquisti.

1. Crei una richiesta di pagamento

Quando il cliente arriva al checkout, crei un record d’ordine con importo, asset e scadenza. Poi assegni a quell’ordine un indirizzo di ricezione unico. Un indirizzo unico per ordine permette di abbinare un trasferimento in arrivo al cliente giusto senza chiedergli di incollare un memo o un riferimento.

Prezzi l’ordine in un’unità stabile, blocchi un importo in ETH per una finestra breve se accetta asset volatili, e memorizzi entrambi i numeri.

2. Il cliente firma e invia

Se il cliente paga da un wallet nel browser, il Suo front end chiede il permesso di usare il suo account, costruisce un oggetto transazione e lo invia. La documentazione di riferimento di eth_sendTransaction di MetaMask descrive questo ordine: ottenere il permesso dell’account, inviare la transazione, conservare l’hash restituito. Se il cliente invece invia da un exchange o da un wallet mobile all’indirizzo che Lei mostra, questo passaggio non lo vede mai. Vede solo il risultato on-chain.

In entrambi i casi, un hash di transazione è il numero di ricevuta del pagamento. Lo memorizzi.

3. Rilevi la transazione

Ha tre opzioni per accorgersi di un pagamento:

• Polling. Chieda a un nodo la ricevuta o il saldo dell’indirizzo ogni pochi secondi. È semplice, ma dispendioso e fragile su scala.
• Sottoscrizioni. Apra un WebSocket verso un nodo e si iscriva ai nuovi blocchi o ai log dei contratti. La documentazione di go-ethereum sugli eventi in tempo reale descrive eth_subscribe proprio per questo. Dovrà gestire da sola le connessioni interrotte e rielaborare i blocchi persi.
• Webhook. Un servizio controlla la catena e chiama il Suo server quando accade qualcosa di rilevante. È l’opzione con la manutenzione minore, ed è quella che sceglie la maggior parte dei team.

Per i token osserva i log degli eventi. La documentazione di Ethereum osserva che le applicazioni possono ascoltare gli eventi dei contratti tramite l’API JSON-RPC e agire sui log che emettono.

4. Confermi il risultato

Inviare non equivale a confermare. La guida MetaMask all’invio di transazioni mostra lo schema: interroghi la ricevuta tramite hash. Se non c’è ricevuta, la transazione è ancora in attesa; uno stato 0x1 indica successo e 0x0 indica fallimento. La documentazione di eth_getTransactionReceipt aggiunge che la ricevuta contiene numero di blocco, gas usato e log.

La macchina a stati del Suo ordine dovrebbe riflettere questo esplicitamente:

1. awaiting_payment: indirizzo emesso, nulla rilevato.
2. pending: una transazione corrispondente è visibile ma non ancora in un blocco.
3. confirmed: ricevuta trovata, stato riuscito, importo e asset corrispondono.
4. final: sono passati abbastanza blocchi aggiuntivi per la Sua tolleranza al rischio.
5. failed, underpaid, overpaid o expired: i casi che richiedono una regola, non un’alzata di spalle.

Quanti blocchi attendere prima di rilasciare la merce è una decisione di business. I beni digitali sotto pochi dollari possono partire alla prima conferma. Gli ordini di valore elevato meritano un’attesa più lunga, perché un blocco può occasionalmente essere riorganizzato prima che la rete lo consolidi.

5. Riconcili

Ogni giorno confronti la somma dei pagamenti confermati nel Suo database con ciò che la catena dice essere arrivato ai Suoi indirizzi. Ogni differenza è un bug, un webhook perso o un cliente che ha pagato l’asset sbagliato. La sezione dati e analisi di ethereum.org elenca gli indicizzatori che servono log storici degli eventi, il che può ridurre quanto di questo lavoro gestisce direttamente Lei.

Come funzionano gas, transazioni fallite e rimborsi?

Il gas è il punto in cui molte prime integrazioni riservano sorprese. Ogni transazione paga una commissione composta da commissione di base e commissione prioritaria, e a pagarla è il mittente, come spiega la documentazione sulle transazioni. Ne derivano tre conseguenze per Lei.

• I clienti possono pagare troppo poco o bloccarsi. Se impostano una commissione troppo bassa, la transazione resta in attesa. Il Suo ordine non dovrebbe scadere mentre una transazione valida è in volo.
• Le transazioni fallite costano comunque gas. Un trasferimento di token annullato produce una ricevuta con stato fallito, e i fondi del cliente non si muovono. Non segni l’ordine come pagato perché ha visto un hash.
• Inviare dal Suo lato le costa. Rimborsi, trasferimenti di svuotamento dagli indirizzi di deposito verso un wallet di tesoreria e pagamenti richiedono tutti gas, e gli indirizzi dei token hanno bisogno di ETH per spostare i token. Stimi la commissione prima dell’invio e la metta in budget.

Nell’API di Chaingateway, gas, gasprice, maxFeePerGas e maxPriorityFeePerGas sono campi opzionali degli endpoint di transazione ETH ed ERC-20, e GET /api/v2/ethereum/gasprice restituisce il prezzo del gas attuale. La nostra guida su come stimare le commissioni del gas su Ethereum e altre catene descrive i metodi di stima.

Se vuole che i clienti paghino senza dover possedere ETH, l’account abstraction permette agli sviluppatori di sponsorizzare le transazioni, come descritto nel tutorial di ethereum.org sulla sponsorizzazione delle commissioni. Aggiunge complessità ai contratti, quindi lo riservi ai prodotti in cui l’attrito del gas costa davvero conversioni.

Per i rimborsi, definisca la politica in anticipo. Rimborsi all’indirizzo mittente solo dopo aver verificato che non sia un indirizzo di deposito di un exchange che Lei non controlla, oppure chieda al cliente un indirizzo di rimborso. Trattenga apertamente la commissione di rete oppure la assorba, ma la scriva nella regola.

Come si proteggono chiavi, firme e contratti?

Chiavi private

Chi detiene la chiave controlla i fondi. Generi le chiavi in un ambiente rafforzato, non le registri mai, non le committi mai, e separi gli hot wallet (saldi piccoli, usati per i pagamenti) dal cold storage (la maggior parte dei fondi). Svuoti gli indirizzi di deposito verso il lato cold secondo una pianificazione.

Autenticità dei webhook

Un endpoint webhook è un URL pubblico che può segnare un ordine come pagato, quindi chiunque lo trovi può inviare un evento falso. Lo protegga in quattro modi:

• Verifichi una firma su ogni richiesta. La firma HMAC è l’approccio comune. Se lo schema include un timestamp, rifiuti quelli vecchi.
• Renda il gestore idempotente, così un recapito duplicato non accredita un ordine due volte.
• Confermi importo e destinatario con una ricerca diretta prima di rilasciare la merce.
• L’header X-Signature di Chaingateway copre solo l’ID della transazione, come spiega l’articolo sulla verifica della firma, quindi la ricerca conta.

Codice dei contratti smart

Se scrive i propri contratti di pagamento, il rischio si sposta sul codice. Il report sulla sicurezza pubblicato da Ethereum osserva che audit, librerie testate, verifica formale e analisi statica migliorano tutti la sicurezza dei contratti, e che il codice personalizzato per controlli avanzati può aumentare il rischio di vulnerabilità. La regola pratica: non distribuisca un contratto personalizzato quando per il Suo caso bastano un indirizzo semplice e gli eventi token standard.

Conviene costruirla da sé o usare un’API?

La strada fai-da-te significa far girare o noleggiare nodi e scrivere un generatore di indirizzi. Lei costruisce anche il decodificatore dei log per ogni token accettato, stima il gas, gestisce le riorganizzazioni e mantiene tutto in funzione. È una strada ragionevole per un team il cui prodotto è l’infrastruttura di pagamento.

Per tutti gli altri, il costo è tempo e manutenzione continua. La questione architetturale è se ricevere gli eventi nel momento in cui accadono o riconciliare in batch più tardi. Per i pagamenti, gli eventi in tempo reale sono il default migliore.

La nostra comparazione dei tipi di API blockchain e quando usare ciascuno ne illustra le categorie. La panoramica su Ethereum spiega ETH, gas e token ERC-20 per i team nuovi alla catena.

Come si integra Chaingateway in un’integrazione Ethereum?

La API Ethereum permette di inviare token ERC-20 via REST, senza web3.js. Tre endpoint coprono gran parte di un flusso di pagamento:

Passo	Endpoint
Creare un indirizzo di deposito	POST /api/v2/ethereum/addresses
Monitorarlo per ETH o token in arrivo	POST /api/v2/ethereum/webhooks con to, url e type (ETH, ERC20 o ERC721)
Inviare ETH o un token ERC-20 in uscita	POST /api/v2/ethereum/transactions oppure .../transactions/erc20

Un pagamento ERC-20 in uscita richiede mittente, destinatario, contractaddress e amount, più la password del wallet per i wallet che l’API ha creato con una password. L’errore 422 per un saldo di commissioni vuoto è insufficient funds for gas * price + value. Lo provi prima sulla Sepolia aggiungendo l’header X-Network: testnet. La pagina Chaingateway Webhooks e la Blockchain API coprono le altre reti supportate con le stesse chiamate.

Le notifiche webhook non riuscite non vengono ritentate automaticamente. Le elenchi con GET /api/v2/ethereum/webhooks/notifications/failed e rinvii ciascuna.

I piani sono fatturati in base all’uso e alle funzionalità: Plus costa 49 € al mese, Pro 99 €, Premium 249 € ed Enterprise 499 €, oppure 490 €, 990 €, 2.490 € e 4.990 € all’anno con fatturazione annuale. Ogni piano inizia con una prova gratuita di 7 giorni senza carta né KYC. Consulti la pagina dei prezzi per sapere cosa include ciascun piano.

Come si testa e si monitora un’integrazione di pagamenti Ethereum?

Un’integrazione di pagamenti non è finita quando funziona la demo. Esegua questa lista su una rete di test prima, poi di nuovo con piccoli importi reali:

• Pagamento esatto, sottopagamento e sovrapagamento di ETH e di ciascun token accettato.
• Pagamento tardivo dopo la scadenza dell’ordine, e pagamento duplicato allo stesso indirizzo.
• Una transazione fallita con un limite di gas basso, così vede una ricevuta fallita e verifica che l’ordine non si completi.
• Webhook duplicati e fuori ordine, riprodotti deliberatamente.
• Il Suo stesso downtime: fermi il server per dieci minuti, invii un pagamento, riavvii e verifichi che nulla si perda.
• Flussi wallet nel front end. I team QA possono fare test di regressione senza detenere chiavi private, usando strumenti come quello indicato nella pagina Impersonator.xyz di ethereum.org.

Dopo il lancio, imposti alert su tre segnali: ordini bloccati in pending oltre una soglia, uno scarto tra i totali del database e i totali on-chain, e i fallimenti nel recapito dei webhook. Il primo intercetta i problemi di commissione, il secondo gli eventi mancati, il terzo le Sue interruzioni.

Fonti

• Transazioni, ethereum.org
• Standard dei token ERC-20, ethereum.org
• eth_sendTransaction, documentazione MetaMask
• eth_getTransactionReceipt, documentazione MetaMask
• Inviare transazioni, documentazione MetaMask
• Eventi in tempo reale, go-ethereum
• Registrare dati dai contratti smart con eventi, ethereum.org
• Sponsorizzare le commissioni del gas, ethereum.org
• Panoramica delle sfide di sicurezza, ethereum.org
• Dati e analisi, ethereum.org
• Impersonator.xyz, ethereum.org

Consigliati

• API Ethereum: inviare token ERC-20 via REST, senza web3.js
• Panoramica Ethereum: ETH, commissioni del gas e token ERC-20 spiegati
• Blockchain API: un’unica API REST per Bitcoin, Ethereum e altre 5 reti
• Ricevere pagamenti crypto in Laravel: guida pratica