Vai al contenuto
Home » 🧭 Howto – Guide Tecniche per Tor, Privacy e Sicurezza » 🛒 Progetto Marketplace su Hidden Service .onion » 💰 Integrazione BTCPay Server – Parte 4

💰 Integrazione BTCPay Server – Parte 4

🧱 Introduzione

In questa quarta parte della guida, implementeremo un sistema di pagamento in Bitcoin tramite BTCPay Server, integrato in WooCommerce su un Hidden Service accessibile via Tor. L’obiettivo è garantire pagamenti anonimi, decentralizzati e compatibili con la logica privacy-preserving adottata in questo progetto.

BTCPay Server è una piattaforma open source, self-hosted, che consente di ricevere pagamenti Bitcoin senza intermediari e con pieno controllo sui fondi. L’uso su Hidden Service richiede una configurazione attenta per garantire compatibilità con .onion, sincronizzazione della blockchain e sicurezza dell’ambiente.

📌 Requisiti: installazione precedente di WooCommerce operativa, accessibile via Tor, e VPS con Docker o installazione bare-metal di BTCPay Server.

🔐 1. Obiettivi della Parte 4

  • Integrare un nodo Bitcoin compatibile con BTCPay Server (es. Bitcoin Core o pruned node)
  • Installare BTCPay Server su ambiente compatibile Hidden Service .onion
  • Collegare BTCPay a WooCommerce tramite plugin ufficiale
  • Ricevere pagamenti Bitcoin su checkout WooCommerce
  • Verificare che l’intera transazione avvenga in modalità anonima

⚙️ 2. Installazione BTCPay Server

🔧 2.1 Setup ambiente di test

BTCPay Server è stato installato come macchina virtuale dedicata su un server Proxmox condiviso, configurata per un ambiente Proof of Concept. La VM dispone di 4 CPU, 8 GB di RAM e 80 GB di storage NVMe, con sistema Debian 12. L’accesso avviene esclusivamente tramite rete VPN o console Proxmox, e il servizio è esposto solo tramite Hidden Service Tor.

Durante la fase di configurazione, è possibile aggiungere temporaneamente la seguente riga al file /etc/hosts del client connesso alla VPN:

172.16.35.191   btcpayserver

Questo consente di raggiungere l’interfaccia web tramite http://btcpayserver, ma solo come misura temporanea. In ambienti di produzione, l’accesso avverrà esclusivamente tramite indirizzo .onion.

📦 Nota tecnica: anche in modalità pruned, Bitcoin Core scarica e verifica tutta la blockchain dalla genesi fino all’ultimo blocco per garantire la validità del nodo. Tuttavia, conserva solo gli ultimi blocchi necessari per la validazione. Questo comporta un tempo di sincronizzazione simile a un nodo full, ma con un notevole risparmio di spazio su disco. La configurazione viene applicata tramite BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s", che abilita prune=1 nel file di configurazione. Ideale per ambienti di test. In produzione, è consigliato l’uso di un nodo full per garantire maggiore autonomia e sicurezza.

📌 Nota: BTCPay Server deve essere installato su una VPS distinta da quella che ospita WordPress/WooCommerce. L’accesso al servizio deve avvenire esclusivamente tramite Hidden Service .onion, con firewall che blocca qualsiasi connessione sulla rete clearnet. È consigliato l’uso di disco cifrato e SSH accessibile solo via Tor.

🔧 2.2 Installazione via Docker (raccomandato)

BTCPay supporta il deploy via Docker Compose. Su una macchina separata (o container isolato):

apt update && apt install docker docker-compose
mkdir btcpay && cd btcpay
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

Copia e incolla il seguente blocco nel terminale per configurare le variabili d’ambiente necessarie. È possibile modificare i parametri (es. BTCPAY_HOST) in base al proprio ambiente, oppure seguire fedelmente la configurazione proposta per riprodurre il PoC descritto nella guida:

export BTCPAY_ENABLE_SSH=false
export NBITCOIN_NETWORK=mainnet
export BTCPAY_ENABLE_TOR=true
export BTCPAY_TOR_REVERSEPROXY=true
export BTCPAY_HOST=btcpaydarknode.local
export BTCPAY_LIGHTNING="none"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s"  # Abilita pruning per contenere lo spazio entro ~50GB
export BTCPAYGEN_EXCLUDE_FRAGMENTS="letsencrypt"             # Disattiva Let's Encrypt per compatibilità .onion

Avvia il container:

. ./btcpay-setup.sh -i

🛠 Una volta completata l’installazione, puoi accedere all’interfaccia web di BTCPay Server in due modalità:

  • Via hostname locale (es. http://btcpaydarknode.local) – configurabile tramite /etc/hosts, utile solo durante la configurazione iniziale in ambiente LAN/VPN.
  • **Via indirizzo **.onion generato automaticamente da Tor – accessibile tramite Tor Browser. Questo è l’accesso raccomandato per ambienti di produzione e integrazioni.

Per recuperare l’indirizzo .onion del tuo BTCPay Server in qualsiasi momento, esegui:

cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostname

L’indirizzo risultante sarà il tuo endpoint sicuro per l’accesso e l’integrazione con WooCommerce.

Al primo accesso ti verrà richiesto di impostare una email e una password per l’account amministratore del server. Successivamente, verrà richiesto di creare il primo store. Per coerenza con l’ambiente PoC descritto in questa guida, è stato utilizzato “MyDrugs” come nome dello store.

Completata la creazione dello store, sarà necessario configurare il wallet. Il sistema ti presenterà due opzioni:

  • I have a wallet
    • Connect an existing wallet: importa un wallet software/hardware esistente
  • I don’t have a wallet
    • Create a new wallet: genera un wallet nuovo direttamente su BTCPay

In questo PoC è stato scelto di creare un nuovo wallet selezionando l’opzione Watch-only wallet. In questa modalità, la chiave privata viene cancellata dal server, aumentando la sicurezza. Le transazioni potranno essere spese solo esportando e utilizzando la chiave privata su un dispositivo esterno.

Durante la configurazione vengono proposte anche opzioni avanzate, come la Optional passphrase (BIP39) e il tipo di indirizzo. Per coerenza con le raccomandazioni attuali, è stato selezionato l’address type Segwit (Raccomandato).

🔐 Importante: al termine della configurazione, BTCPay Server mostrerà una Recovery Phrase composta da 12 parole. Anche se si tratta di un ambiente di test, è essenziale comprendere che chiunque entri in possesso di questa frase potrà controllare i fondi associati. Salvala in un luogo sicuro e non condividerla mai.

In ambienti di produzione, tutto l’accesso dovrà avvenire esclusivamente tramite il servizio .onion generato automaticamente.

ℹ️ Attendi la sincronizzazione del nodo

È possibile configurare lo store WooCommerce e collegarlo a BTCPay Server anche se la sincronizzazione del nodo Bitcoin non è ancora completa. Tuttavia, fino al completamento della sincronizzazione, non sarà possibile generare nuovi invoice né accettare pagamenti.

Anche in modalità pruned, il nodo Bitcoin deve scaricare e validare tutti i blocchi dalla genesi per poter operare correttamente. Questo processo può richiedere diverse ore o giorni, a seconda della velocità di rete e delle risorse disponibili.

Nel caso specifico di questa guida, la sincronizzazione è avvenuta su una Virtual Machine su Proxmox con 4 CPU, 8 GB di RAM e storage NVMe da 80 GB, completandosi in meno di 24 ore e utilizzando circa 64 GB di spazio su disco. Su un nodo locale nel mio HomeLab, dotato di hardware simile ma con connessione internet meno performante rispetto alla VM in datacenter (1 Gbps), lo stesso processo ha richiesto quasi una settimana. Questo dimostra quanto la rete incida significativamente sui tempi di sincronizzazione, anche in presenza di risorse hardware adeguate.

Puoi monitorare lo stato di sincronizzazione direttamente dal pannello di controllo web di BTCPay Server. Durante questa fase, la dashboard mostrerà il messaggio: “Your node is synching the entire blockchain and validating the consensus rules.” Una volta completato il processo, questo messaggio scomparirà e il nodo sarà operativo per accettare pagamenti Bitcoin.

🔗 3. Integrazione con WooCommerce

🔌 3.1 Installazione plugin

Accedi a WordPress → Plugin → Aggiungi Nuovo:

  • Cerca “BTCPay for WooCommerce”
  • Installa e attiva il plugin ufficiale

🧾 3.2 Configurazione parametri BTCPay

  • Accedi a BTCPay (.onion)
  • Vai su Store → Settings → e copia lo Store ID
  • Vai su Store → Settings → Access Tokens
  • Clicca su “Create Token” per generare una BTCPay API Key con i permessi per WooCommerce
  • Copia la chiave generata

⚙️ 3.3 Configurazione parametri WooCommerce

Nel pannello WordPress → WooCommerce → Settings → BTCPay Settings:

  • Inserisci il valore nel campo BTCPay Server URL (l’indirizzo .onion del tuo BTCPay Server)
  • Incolla la API key generata nel campo dedicato
  • Inserisci lo Store ID copiato in precedenza
  • Scorri in fondo alla pagina e clicca su Save changes per applicare la configurazione

✅ Ora WooCommerce è pronto per ricevere pagamenti Bitcoin direttamente sul tuo nodo, senza intermediari.

🧪 4. Test transazione

  • Accedi a WordPress → WooCommerce → Settings → Payments
  • Disattiva eventuali gateway predefiniti (es. Cash on delivery)
  • Attiva il metodo “BTCPay” configurato nella sezione precedente
  • Aggiungi un prodotto al carrello e procedi al checkout
  • Seleziona “Bitcoin” come metodo di pagamento
  • Se la sincronizzazione del nodo è completa, BTCPay genererà un invoice valido e accessibile via Tor
  • Verifica che il pagamento venga confermato sulla dashboard BTCPay genererà un invoice valido e accessibile via Tor
  • Verifica che il pagamento venga confermato sulla dashboard BTCPay

⚠️ Sicurezza e considerazioni operative

  • Esegui BTCPay su VPS dedicata, con disco cifrato e accesso SSH solo via Tor
  • Disabilita porte non necessarie lato clearnet
  • Mantieni aggiornati BTCPay, Docker, e il nodo Bitcoin
  • Evita connessioni incrociate tra clearnet e .onion per preservare l’anonimato

🧰 Troubleshooting nodo Bitcoin

In alcune configurazioni BTCPay Server può mostrare errori relativi a blocchi Bitcoin marcati come invalidi. Questo problema si manifesta nel log di bitcoind con messaggi simili a:

ERROR: AcceptBlockHeader: block 00000000000000000001ebde... is marked invalid

🔍 Verifica dei log

Controlla i log del container Bitcoin:

docker logs -f btcpayserver_bitcoind

🛠 Risoluzione (reconsiderblock)

Quando un blocco viene marcato come invalido, è possibile forzare la sua rivalutazione tramite il comando:

/root/BTCPayServer/btcpayserver-docker/bitcoin-cli.sh reconsiderblock <block_hash>

oppure:

/usr/local/bin/bitcoin-cli.sh reconsiderblock <block_hash>

Esempio:

/root/BTCPayServer/btcpayserver-docker/bitcoin-cli.sh reconsiderblock 000000000000000000088405a575aeaf0fd6bc070138c3b769f2aedfec006b69

✅ Conclusione

Hai ora un sistema completamente funzionante che integra WooCommerce e BTCPay Server su Hidden Service .onion. Tutti i componenti, dalla cifratura dei dati sensibili alla gestione autonoma dei pagamenti in Bitcoin, sono stati configurati per operare in ambienti Tor-based, mantenendo un buon livello di anonimato e controllo.

🔐 Per soluzioni avanzate, supporto IT o deploy automatizzati, visita la sezione Soluzioni IT per Aziende e Privati del mio sito. La guida fornisce una base completa per la creazione di un ambiente e-commerce su Hidden Service, ma non include tutti gli aspetti avanzati di sicurezza operativa, come hardening del sistema, monitoraggio dei log, firewall evoluti o gestione dei rischi reali. Per chi desidera estendere questo progetto in modo professionale o metterlo in produzione in totale sicurezza, offro consulenze e supporto tecnico personalizzato.