Questo articolo è una guida all’utilizzo di BTCPay Server, un software free e open-source che permette di accettare pagamenti in bitcoin.
Questa guida è rivolta a chi vuole accettare pagamenti in bitcoin nella propria attività commerciale.
BTCPay Server è un processore di pagamento open-source e self-hosted: è sicuro, privato, peer-to-peer, resistente alla censura e gratuito. Il progetto è partito dall’idea e dallo sviluppo di Nicolas Dorier, dopo che nel 2017, durante la Blocksize War, l’azienda BitPay invitò gli utenti a scaricare un software incompatibile con Bitcoin per motivi di sicurezza. Oggi, il software è sviluppato e mantenuto interamente da centinaia di collaboratori volontari in tutto il mondo. Puoi trovare il repository ufficiale su GitHub.
Indice
- Modalità di utilizzo
- Creazione di un account
- Creazione di uno Store
- Creazione wallet onchain
- Creazione wallet LNbank
- Come incassare bitcoin
- Creazione applicazione Point-of-Sale
- Come gestire la contabilità
- Payment Requests
- Pull payments
- Come effettuare il rimborso di un pagamento
- Funzioni avanzate
- Conclusione
Modalità di utilizzo
Innanzitutto dovrai decidere se vuoi ospitare un’istanza (“installazione di un programma”) personale BTCPay Server, oppure utilizzare un’istanza ospitata da una terza parte.
La cosa migliore sarebbe che ogni commerciante ospitasse la propria istanza sul proprio full node Bitcoin.
Installazione manuale su server fisico personale
Con questa modalità, per poter utilizzare BTCPay Server occorrerà installare il software su un proprio computer (server) che rimarrà sempre acceso.
Per installare BTCPay Server occorre prima installare:
- Bitcoin Core;
- .NET Core;
- NBXplorer come block explorer;
- PostgreSQL come database;
- Nginx;
- Lightning Network Daemon (LND), Core Lightning (CLN) o Eclair come implementazione Lightning;
- ThuderHub o Ride The Lightning (RTL) come software di gestione del nodo.
Questa è la modalità migliore per essere un business completamente self-sovereign e indipendente, poiché hai il controllo completo dell’hardware del tuo full node. Ovviamente questa modalità non è adatta a tutti poiché il processo di installazione richiede un minimo di esperienza informatica.
Se hai un’attività commerciale che riceve molti pagamenti in bitcoin, questa è la soluzione migliore per utilizzare BTCPay Server.
Implementazione full node Bitcoin + BTCPay Server
Questa modalità di utilizzo prevede l’installazione di una “distribuzione” di un full node Bitcoin. Esistono diverse implementazioni di full node Bitcoin che permettono di installare BTCPay Server.
Ecco un elenco di alcune delle implementazioni di full node Bitcoin più note:
In ogni distribuzione potrai trovare l’applicazione di BTCPay Server da dover installare sul nodo. Una volta installata, potrai utilizzare BTCPay Server.
Installazione in cloud
In questo caso andrai ad effettuare l’installazione di BTCPay Server in cloud tramite un hosting provider. Il tradeoff principale di questo setup è il fatto di non avere il controllo sull’hardware che andrai ad utilizzare.
Le soluzioni più semplici per installare BTCPay Server in cloud sono:
Voltage è una soluzione interessante per chi desidera una soluzione già pronta all’uso, senza dover effettuare alcun tipo di installazione. Voltage ti permette di ospitare un light client (Neutrino) e il software BTCPay Server. In questo video tutorial puoi vedere come utilizzare Voltage per poter ospitare BTCPay Server.
Un’altra opzione è quella di installare BTCPay Server su Lunanode, un hosting provider canadese che permette l’installazione di BTCPay Server in pochi minuti. Infatti, seguendo la guida ufficiale, l’installazione risulta molto semplice e veloce.
Altra soluzione simile è l’installazione attraverso l’hosting provider Dream Lab Network. Qui puoi trovare la guida ufficiale per l’installazione di BTCPay Server.
Un’altra opzione è l’installazione sulla piattaforma Microsoft Azure. Anche in questo caso basterà seguire la guida fornita dalla documentazione ufficiale di BTCPay Server.
Un altro tipo di soluzione possibile è l’installazione di BTCPay Server su una VPS di un hosting provider come Amazon Web Services (AWS) EC2, Contabo, Digital Ocean o Google Cloud.
Utilizzo di un’istanza ospitata da una terza parte
In questo caso l’utente sceglie di non utilizzare una propria istanza, ma di affidarsi all’istanza BTCPay Server di una terza parte. Questa terza parte può essere chiunque: un amico, una community o una società.
In questa guida utilizzerò l’istanza messa a disposizione gratuitamente dalla community di BTCPay Server Italia.
Creazione di un account
La prima operazione da fare per poter utilizzare BTCPay Server nella propria attività commerciale è quella di registrarsi creando un proprio account.
Per questa guida utilizzeremo l’istanza messa a disposizione dalla community di BTCPay Server Italia. Collegati al sito ufficiale e clicca su Registrati.
Ti basterà inserire un’e-mail e una password per creare il tuo account.
Creazione di uno Store
Uno Store è paragonabile a un negozio che decide di accettare pagamenti in bitcoin. Su BTCPay Server è possibile creare infiniti store. Ogni utente può creare e gestire più store. Ogni store avrà un suo wallet e se lo si desidera anche delle applicazioni come un PoS, una campagna crowdfunding o un pulsante di pagamento.
Per creare uno store vai in alto a sinistra e clicca su Create Store. Inserisci il nome del negozio nel campo di testo Name, inserisci la valuta che desideri utilizzare e scegli la fonte da cui ottenere il prezzo di bitcoin. Infine fai clic su Create.
Una volta creato il tuo store, cliccando su Settings potrai andare a modificare le impostazioni predefinite (tempo scadenza dell’invoice, valuta predefinita, checkout appearance) del tuo negozio.
Creazione wallet onchain
Ora è il momento di creare un wallet onchain.
La creazione di un wallet onchain è la prima operazione da effettuare per poter iniziare ad accettare pagamenti in bitcoin.
La procedura consigliata è quella di creare un wallet esternamente, fuori dall’istanza BTCPay Server. In questo modo le chiavi private del wallet non rimarranno online sul server, ma si troveranno su un dispositivo dedicato come uno smartphone, un computer o un hardware wallet.
Per impostare un wallet onchain su BTCPay Server, clicca su Set up a wallet.
Successivamente clicca su Connect an existing wallet.
Seleziona la voce Enter extended public key.
Dopo aver creato il wallet dovrai importare la master public key (xpub) in BTCPay Server. In questo modo ogni volta che il software genererà un’invoice, verrà utilizzato sempre un nuovo indirizzo bitcoin per ricevere fondi, evitando così il fenomeno noto come address-reuse.
Alcuni dei wallet consigliati da poter utilizzare in coppia con BTCPay Server sono:
Per una maggiore sicurezza, puoi utilizzare BTCPay Server insieme a un hardware wallet Ledger, Trezor, BitBox, Blockstream Jade o Coldcard. Per farlo, segui la guida ufficiale. Ti basterà scaricare il software BTCPay Vault e successivamente collegare l’hardware wallet al tuo computer.
Creazione wallet con BlueWallet
In questa guida utilizzerò BlueWallet per la creazione di un wallet onchain.
Per creare un nuovo portafoglio, clicca sul tasto Aggiungi ora che trovi nella homepage. Dai un nome al portafoglio e seleziona la voce Bitcoin come tipo di portafoglio.
Nella schermata successiva ti verrà mostrata la mnemonic phrase del portafoglio. La mnemonic phrase è il backup del tuo portafoglio ed è fondamentale in caso di ripristino del wallet. Salvala offline, ad esempio su carta o acciaio. Non salvarla digitalmente (niente foto, niente screenshot, niente copia-incolla). Non rivelare mai queste parole! Rivelare queste parole a qualcuno significa consegnargli la proprietà dei tuoi bitcoin. Puoi verificare la tua mnemonic phrase anche dopo la creazione del portafoglio sotto la voce Esporta/Backup.
Dopo aver salvato offline la tua mnemonic phrase, clicca su OK, l’ho scritto. Ora potrai vedere la card del tuo wallet sulla schermata principale di BlueWallet.
Ora clicca sulla card del wallet e successivamente sui tre puntini in alto a destra. Infine clicca su Mostra XPUB; copia l’xpub e torna sulla schermata di BTCPay Server.
Ora inserisci l’xpub nell’apposito campo di testo e clicca su Continue. Controlla che i primi indirizzi mostrati su BTCPay Server corrispondano a quelli mostrati su BlueWallet.
In questo modo avrai creato un wallet Bitcoin onchain sul tuo smartphone tramite BlueWallet e l’avrai importato come wallet watch-only su BTCPay Server. Tramite BTCPay Server potrai visualizzare il saldo del portafoglio e le transazioni.
Creazione wallet LNbank
LNbank è una funzionalità di BTCPay Server che ti permette di utilizzare il nodo Lightning del proprietario dell’istanza in modalità custodial. Puoi considerare un wallet LNbank come un account sul nodo Lightning del proprietario dell’istanza BTCPay Server.
LNbank è un plugin sviluppato dal team di BTCPay Server che permette, a chi non ha un nodo Lightning, di creare un account sul nodo della persona che ospita l’istanza di BTCPay Server.
Difatti ogni wallet LNbank è un wallet custodial Lightning Network. Essendo custodial, è consigliato tenere una piccola quantità di satoshi nel wallet. Puoi spostare i fondi subito dopo averli ricevuti.
Per creare un wallet LNbank, clicca sulla voce LNbank, inserisci il nome del wallet e clicca Create. Cliccando nuovamente su LNbank potrai vedere tutti i tuoi wallet LNbank.
Ora clicca sulla voce Lightning nel menù di sinistra per impostare il tuo wallet LNbank come metodo per ricevere pagamenti Lightning Network.
Seleziona la voce Use LNbank wallet.
In basso seleziona il wallet LNbank su cui vuoi ricevere i pagamenti Lightning. In questo caso seleziono il wallet Test appena creato.
Infine clicca su Save.
D’ora in poi riceverai tutti i pagamenti Lightning nel wallet LNbank che hai creato.
Puoi anche collegare il wallet LNbank a un wallet mobile come BlueWallet, Zeus o Alby. Per farlo ti basterà cliccare sulle impostazioni e successivamente sulla voce Show QR Code.
Scansiona il QR Code con BlueWallet, Zeus o Alby per importare il tuo wallet LNbank sul tuo smartphone.
Per maggiori informazioni su LNbank, consulta la pagina ufficiale.
Come incassare bitcoin
Il modo per poter incassare bitcoin su BTCPay Server è quello di creare un’invoice di pagamento.
Un’invoice è un documento emesso dal venditore per riscuotere il pagamento. Le invoice hanno una scadenza perché bloccano il tasso di cambio entro un determinato periodo di tempo per proteggere il destinatario dalle fluttuazioni del prezzo di bitcoin.
Puoi creare un’invoice manualmente oppure generarla tramite le applicazioni Point-of-Sale, Crowdfunding o tramite un Pay Button.
Prima di creare un’invoice, vai nelle impostazioni del tuo store e imposta il metodo di pagamento predefinito. Seleziona BTC Off-chain per settare Lightning Network come metodo di pagamento predefinito. Puoi impostare delle soglie per cui il metodo di pagamento predefinito varia da onchain a off-chain. Puoi anche impostare la lingua predefinita della schermata di checkout.
Ora, per creare un’invoice manualmente, clicca sulla voce Invoice nel menù a sinistra e successivamente clicca Create Invoice.
Ora dovrai inserire manualmente i dati dell’invoice: somma da pagare, valuta, id ordine, descrizione dell’oggetto, metodo di pagamento predefinito, informazioni del cliente, e-mail del cliente e possibilità di richiedere una e-mail per un eventuale rimborso. Infine clicca su Create.
Clicca su Checkout per pagare l’invoice.
Scansiona il QR Code con un wallet Lightning Network per pagare la somma richiesta.
Pagamento effettuato!
Cliccando su View receipt, puoi vedere la ricevuta (“scontrino”) del pagamento.
Clicca su Details per vedere i dettagli dell’invoice pagata.
Puoi notare come lo stato dell’invoice sia passato da New a Settled, cioè da nuovo a pagato.
Come inviare bitcoin da LNbank a un wallet Lightning Network
Dopo aver ricevuto il pagamento, cliccando su LNbank, potrai notare che i fondi appena ricevuti sono finiti nel tuo wallet LNbank.
Cliccando sul wallet e successivamente cliccando sulla voce Send, potrai spedire i tuoi fondi in un wallet Lightning personale (come wallet Lightning Network non-custodial ti consiglio Phoenix o Breez).
Per ricevere fondi su un tuo wallet Lightning dovrai creare un’invoice e successivamente incollarla nel campo di testo della pagina Send su BTCPay Server. Puoi inserire anche un lightning address o una richiesta LNURL.
Scrivi una descrizione del pagamento e clicca su Send 54.000 sats.
Una volta inviati i fondi al tuo wallet Lightning Network, potrai vedere nel wallet LNbank il riepilogo e l’elenco delle transazioni passate dal portafoglio.
Se vuoi spostare dei satoshi da un wallet Lightning Network a un wallet onchain puoi utilizzare il servizio Boltz.
Creazione applicazione Point-of-Sale
Per creare un Point of Sale su BTCPay Server, clicca su New app.
Ora seleziona Point of Sale e dai un nome alla tua app.
Seleziona Keypad only come stile del PoS e completa gli altri dati richiesti.
Cliccando su View potrai vedere il tuo PoS. Puoi salvare il link URL del PoS e utilizzarlo su qualsiasi dispositivo (smartphone o tablet) per ricevere pagamenti in bitcoin.
Con questo PoS puoi creare invoice istantaneamente, inserendo la somma da far pagare al cliente. Puoi anche inserire una percentuale di sconto cliccando su Discount oppure una percentuale di mancia cliccando su Tip.
Come gestire la contabilità
Per gestire la contabilità su BTCPay Server vai alla pagina Invoices. In questa schermata puoi trovare l’elenco di tutte le transazioni avvenute, sia onchain sia Lightning Network. Da questa pagina puoi esportare un file CSV e scaricarlo sul tuo computer. Per farlo, clicca sulla voce Reports in alto a destra, scegli quale tipologia di pagamento visualizzare e successivamente clicca su Export CSV in alto a destra.
Hai anche la possibilità di cercare le invoice per Invoice Id oppure di filtrare le invoice per store, id dell’ordine, id dell’articolo, stato o data dell’invoice.
In questo modo puoi vedere il report delle transazioni avvenute in un file CSV.
Payment Requests
Le Payment Requests sono invoice dinamiche che possono essere condivise tramite link URL e pagate in qualsiasi momento utilizzando il tasso di cambio al momento del pagamento. Il cliente può anche pagare la payment request con pagamenti parziali. La payment request rimarrà valida finché non sarà stata pagata per intero o, se stabilita, fino alla sua data di scadenza.
Per creare una Payment Request, clicca sulla voce Requests nel menù a sinistra e successivamente clicca su Create Payment Request.
Inserisci i dati della richiesta di pagamento e infine clicca su Create.
Ora clicca su View per visualizzare la payment request.
Adesso potrai condividere la payment request tramite link URL. Clicca su Copy Link e invia la richiesta di pagamento al cliente. La richiesta di pagamento rimarrà valida fino a quando il pagamento non sarà completato o fino alla sua scadenza.
Per pagare la payment request il cliente dovrà cliccare su Pay Invoice e scansionare l’invoice con un wallet.
Pagamento effettuato!
Puoi notare come lo stato della payment request sia passato a Settled, poiché il pagamento è stato completato interamente.
Pull payments
L’idea dietro ai pull payments è quella di invertire il processo di invio di una transazione bitcoin. Invece di inviare direttamente il pagamento al fornitore, il cliente può consentire al fornitore di “prelevare” la somma stabilita quando lo ritiene opportuno. Questo processo è noto come pull payment. Questo metodo di pagamento apre la strada a nuove applicazioni, tra cui:
- Servizi di abbonamento in cui l’abbonato consente al servizio di prelevare denaro ogni X tempo;
- Rimborsi in cui il commerciante permette al cliente di prelevare il denaro per il rimborso nel proprio wallet quando lo ritiene opportuno;
- Fatturazione per i freelance, basata sulle ore di lavoro: il cliente permette al freelance di prelevare il denaro dal suo portafoglio man mano che le ore di lavoro vengono registrate;
- Mecenatismo: il mecenate permette al destinatario di prelevare denaro ogni mese per continuare a sostenere il suo lavoro;
Per creare un pull payment, vai alla voce Pull payments e clicca Create pull payment.
Inserisci i dati richiesti e clicca su Create.
Ora cliccando su View potrai vedere la schermata del pagamento.
Condividi il link URL con il fornitore. Egli dovrà inserire un indirizzo bitcoin oppure un’invoice Lightning e successivamente cliccare su Claim Funds.
Una notifica ti arriverà nella home di BTCPay Server.
Clicca su Approve & Send selected payouts per approvare e inviare il pagamento.
Ora invia la transazione.
Payouts
La sezione Payouts fornisce una panoramica dei pagamenti correnti e del loro stato. Questa funzione ti consente di elaborare i pull payments. Qui trovi le opzioni per approvare e inviare direttamente l’importo del pagamento richiesto. Quando ci sono più casi di pull payments, questi possono essere selezionati e raggruppati per l’invio in una sola volta.
Come effettuare il rimborso di un pagamento
Il rimborso di un pagamento è una delle applicazioni costruite grazie ai Pull payments.
Per effettuare il rimborso di un pagamento, vai alla sezione Invoice. Vai nei Dettagli di un’invoice e clicca il tasto Issue Refund in alto a destra.
Scegli la somma da rimborsare.
Condividi il link URL di questa pagina con il cliente che deve ottenere il rimborso.
Il cliente dovrà inserire un’invoice Lightning, un LNRUL o un Lightning Address. L’invoice Lightning deve avere una scadenza di 30 giorni. Per questo motivo risulta più facile inserire un Lightning Address o un link LNURL. In questo caso inserisco un Lightning Address. Infine il cliente dovrà cliccare su Claim Funds.
Una volta che il cliente ha effettuato la richiesta di rimborso, verrà notificato un avviso sulla home del commerciante. Rimane soltanto da effettuare il pagamento al cliente.
Cliccando su Payouts e scegliendo il metodo di pagamento desiderato, potrai vedere la lista di tutti i tuoi payout. In questo caso vi è un payout in attesa del pagamento.
Seleziona il payout e clicca su Actions > Send selected payouts.
Effettua il pagamento.
Rimborso effettutato!
Procedura di rimborso completata.
Ricorda che la stessa procedura di rimborso può essere effettuata sia per pagamenti Lightning Network che per transazioni onchain.
Funzioni avanzate
- Lightning Address: con questa funzione hai la possibilità di creare degli indirizzi Lightning simili a una e-mail per poter ricevere satoshi; per farlo, clicca su Lightning Address e poi su Create Address;
- Hai la possibilità di unificare in un unico QR Code sia il QR Code per pagamenti onchain che il QR Code per pagamenti Lightning Network: per attivarlo, vai nelle impostazioni del tuo Store e clicca sulla voce Checkout Appearance;
- Hai la possibilità di etichettare gli indirizzi con l’opzione Labels;
- PodServer: un plugin che ti permette di ospitare il tuo podcast e guadagnare satoshi tramite le funzionalità di Podcasting 2.0;
- Pay button: questo plugin ti permette di creare un pulsante di pagamento da mettere sul tuo sito o blog per ricevere donazioni e mance;
- Nostr NIP-05: questo plugin ti consente di verificare il tuo account di Nostr attraverso BTCPay Server;
- Hai la possibilità di inviare bitcoin da BTCPay Server con un hot wallet o attraverso transazioni PSBT;
- Supporta transazioni RBF (Replace by fee);
- Hai la possibilità di scegliere quale UTXO spendere attraverso la coin selection;
- Supporta la connessione a Tor;
- Supporta il PayJoin: per poter ricevere transazioni PayJoin dovrai utilizzare un hot wallet creato su BTCPay Server;
- Possibilità di effettuare CoinJoin utilizzando il protocollo Wabisabi. Ti basterà installare il plugin CoinJoin per migliorare la privacy dei tuoi bitcoin;
- Crowdfunding app: questa app ti consente di creare una campagna di crowdfunding simile a Kickstarter o Indiegogo. A differenza delle piattaforme di crowdfunding tradizionali, il creatore della campagna è il proprietario della piattaforma. I fondi arrivano direttamente al wallet del creatore della campagna senza alcuna commissione;
- Integrazione con le seguenti piattaforme: WooCommerce, Shopify, Drupal, Magento, PrestaShop, OpenCart e Zapier;
- Disponibilità delle API per integrazioni personalizzate.
Conclusione
A mio parere, BTCPay Server è il gold standard dei processori di pagamento bitcoin. Se vuoi accettare pagamenti in bitcoin in maniera intelligente, BTCPay Server è il software che fa per te. Ad ogni aggiornamento vengono aggiunte nuove funzioni e vengono corretti bug e vulnerabilità. Più utilizzerai BTCPay Server, più conoscerai tutti i suoi aspetti e le sue funzionalità.
Qui puoi trovare la documentazione completa di riferimento.
BTCPay Server è anche perfetto per chi desidera sostituire processori di pagamento alternativi che pretendono una commissione sulle transazioni o che richiedono di effettuare il processo di KYC (Know Your Customer) & AML (Anti-money laundering).
Se questo contenuto ti è piaciuto, considera la possibilità di fare una donazione scansionando il QR code qui sotto con un wallet Lightning Network.
3 Responses