Todo processador de cartão e todo gateway de cripto hospedado fica entre você e o seu cliente, cobra um percentual, guarda a lista de quem pagou o quê para você, e reserva o direito de parar. O BTCPay Server é o software que os remove: um processador de pagamento de código aberto, auto-hospedado e não custodial, onde as moedas vão direto para uma carteira da qual o servidor não consegue gastar. Seis passos até um checkout funcional de Bitcoin e Lightning em uma máquina alugada anonimamente — o formato do nó que decide o orçamento, a chave somente leitura, o problema da liquidez de entrada, e a regra de backup que o Lightning quebra. A máquina custa $7.90 por mês. Testado no Debian 12.
Escolher
Nó completo, podado ou externo
Provisionar
Domínio primeiro, depois quatro portas
Implantar
Um gerador, um comando
Conectar
Chave somente leitura, nunca uma seed
Lightning
Canais e capacidade de entrada
Lançar
Checkout, backups, atualizações
Um pagamento em uma blockchain não precisa de uma empresa no meio. O cliente assina uma transação, a rede a confirma, e o dinheiro é seu — não há adquirente, não há janela de liquidação e não há ninguém cuja aprovação o pagamento dependa. Esse é todo o objetivo da coisa, e é por isso que a tecnologia existe.
Então uma loja precisa realmente receber pagamentos, e as exigências práticas chegam todas de uma vez. Toda fatura precisa do próprio endereço, para que os pagamentos possam ser distinguidos. Alguém precisa observar a cadeia e decidir quando uma fatura está paga. O valor precisa ser cotado em uma moeda que o cliente pense, a uma taxa que se mantenha por tempo suficiente para ele apertar enviar. O status do pedido precisa fluir de volta para a loja. E tudo isso precisa funcionar às duas da manhã sem ninguém observando. Construir tudo isso é um projeto; não construir é por isso que quase todo mundo se cadastra em um gateway hospedado em vez disso — e, no espaço de um formulário, recoloca um intermediário em um sistema que foi desenhado para não ter um.
Vale a pena declarar com clareza o que esse intermediário guarda, porque é mais do que a taxa. Ele guarda as moedas, pelo menos até que um repasse seja executado, o que significa que ele pode atrasar um. Ele guarda a lista: cada cliente, cada valor, cada timestamp, cada produto, em um banco de dados que você não consegue ler nem apagar. Ele guarda um arquivo de identidade sobre você, porque uma empresa que lida com o dinheiro de outras pessoas é obrigada a coletar um. E ele guarda o interruptor, porque os termos de serviço reservam o direito de decidir que o seu negócio não é mais bem-vindo — uma decisão que chega por e-mail, se aplica tanto ao saldo quanto à conta, e não é, na prática, recorrível.
O BTCPay Server é a resposta para exatamente esse problema, e para nenhum outro. É um processador de pagamento gratuito e de código aberto que você roda na sua própria máquina: ele deriva um endereço por fatura, observa a cadeia, cota preços em moeda fiduciária, expõe um checkout e uma API, e fala Lightning. Ele nunca guarda as suas moedas, porque a carteira que ele observa já é sua. Quatro formas de receber um pagamento em cripto, e o que cada uma realmente custa:
| Propriedade | Um gateway de cripto hospedado | Um endereço puro no rodapé | BTCPay na instância de outra pessoa | BTCPay no seu próprio VPS |
|---|---|---|---|---|
| Quem guarda as moedas | O gateway, até o repasse | Você | Você — ela observa, ela não consegue gastar | Você — ela observa, ela não consegue gastar |
| Quem pode te impedir de negociar | O gateway, por e-mail | Ninguém | O operador da instância | Ninguém |
| Quem vê cada cliente e valor | O gateway, permanentemente | Todo mundo — um endereço, um total público | O operador da instância | Você |
| Documento de identidade exigido | Sim, antes do primeiro repasse | Não | O que quer que o operador peça | Não |
| Custo por transação | Um percentual, para sempre | Nada | Nada | Nada — $7.90 por mês, fixo |
| Distingue uma fatura da outra | Sim | Não — você reconcilia manualmente | Sim | Sim |
| Escolha-o quando | Você quer operação zero e aceita os termos | Doações, um punhado por ano | Você quer o software, mas não o servidor | O faturamento é seu, e a lista também |
A segunda coluna também não é piada nenhuma — um único endereço em um rodapé é genuinamente adequado para um link de doação, e fingir o contrário vende software que ninguém precisa. Deixa de ser adequado no instante em que duas pessoas pagam o mesmo valor no mesmo dia, ou no instante em que você preferiria que a sua renda anual não fosse um número público que qualquer um pode somar.
Um processador de pagamento precisa conseguir responder com honestidade a uma pergunta: essa fatura foi paga? Responder a isso significa observar a rede Bitcoin, e observá-la corretamente significa rodar um nó que valida os blocos por conta própria, em vez de acreditar no que alguém diz. Esse nó é todo o orçamento de hardware deste projeto — o BTCPay em si, o indexador e o banco de dados juntos são um erro de arredondamento perto dele.
Existem três arranjos que fazem sentido, e um que não faz. Um nó arquivístico guarda todo bloco já minerado: folgadamente acima de 700 GB em 2026, e crescendo cerca de 50 GB por ano. É o que você quer se também pretende rodar um explorador de blocos ou fazer análise histórica, e é exagero para uma loja. Um nó podado baixa e valida totalmente cada bloco exatamente da mesma forma, e depois descarta os antigos e mantém uma janela móvel. O modelo de segurança é idêntico — essa é a parte que as pessoas erram, porque "podado" soa como "parcial", e não é — e o gerador de implantação já vem com fragmentos prontos para isso.
Um nó externo é a terceira opção: apontar a pilha para um nó Bitcoin que você já opera, por um link privado. Se você já seguiu o guia do nó Lightning, não há motivo para manter uma segunda cópia da cadeia, e uma VPN mesh entre as duas máquinas é a forma limpa de conectá-las. O arranjo que não faz sentido é apontar uma loja para o nó público de um estranho: ele aprende todo endereço que você está observando, que é o seu faturamento, e está em posição de mentir sobre se uma fatura foi paga.
| Implantação | Cadeia em disco | Volume total necessário | O que você abre mão |
|---|---|---|---|
| Podado, menor janela | ~5–25 GB | ~40 GB | Re-escaneamentos, e qualquer margem de erro. A configuração menor não é recomendada. |
| Podado, janela de ~50 GB | ~50 GB | ~80 GB | Nada que uma loja perceba. O piso sensato. |
| Podado, janela de ~100 GB | ~100 GB | ~140 GB | Nada. O padrão confortável, com espaço para o Lightning. |
| Arquivístico, histórico completo | 700 GB + | ~960 GB | Nada — mas você paga por isso todo mês, para sempre. |
| Nó externo que você já roda | Nenhuma nesta máquina | ~40 GB | Independência — o checkout fica fora do ar quando a outra máquina fica. |
Um nó podado não consegue re-escanear blocos que já descartou. Na prática, isso significa que ele não consegue reconstruir o histórico de uma carteira cujas transações são anteriores à implantação — o indexador escaneia para frente a partir do dia em que você conecta a chave, então pagamentos antigos para aquela conta simplesmente não vão aparecer na loja. Isso não é um problema se você fizer o que o passo 04 recomenda e der à loja uma conta recém-criada; é uma tarde genuinamente confusa se você conectar uma carteira que já usa há três anos e metade do histórico dela estiver faltando. Decida qual dos dois é o seu caso antes de instalar, não depois.
Mais uma decisão pertence aqui, e não depois, porque muda o que o instalador constrói: se você quer o Lightning desde o primeiro dia. Somente on-chain é uma configuração completa e um lugar perfeitamente respeitável para começar. Adicionar o Lightning depois é suportado e não é doloroso, mas é um segundo daemon com fundos próprios e regras de backup próprias, e há muito a se dizer em favor de provar que dinheiro de verdade chega pelo caminho simples antes de introduzir o complicado.
Peça a máquina. No painel: Order → VPS → Garrison, imagem Debian 12, no bastião onde você quiser que os registros da loja vivam — Helsinque, Estocolmo, Oslo ou Reykjavík. O Garrison é o padrão certo porque comporta uma cadeia podada de 100 GB, um nó Lightning e o banco de dados sem que você tenha que pensar em disco de novo por anos. O Sentinel funciona com uma poda mais apertada; o Bulwark é o plano para um nó arquivístico. Nenhum endereço de e-mail é exigido para abrir a conta, e a fatura é paga em Monero, Bitcoin, Lightning ou qualquer outro ativo suportado — o que é a parte agradável deste projeto em particular, já que você está construindo uma máquina para receber pagamentos em cripto e pagando por ela com um.
Depois, execute o checklist de hardenização da primeira hora antes de qualquer outra coisa — SSH somente por chave em uma porta trocada, atualizações automáticas, um firewall que nega tudo por padrão. Esta máquina vai eventualmente guardar o registro de cada cliente que você tem e o material de chave de um nó Lightning com fundos ativos nele. Não é uma máquina para deixar com autenticação por senha por uma semana.
Agora o registro de DNS, e faça isso antes de rodar o instalador, não depois. Escolha o hostname onde o checkout vai morar — shop.example.com, pay.example.com, o que fizer sentido — e aponte um registro A para o endereço do VPS, mais um AAAA se você quiser alcance via IPv6. Deixe propagar. O proxy reverso que o instalador configura vai tentar obter um certificado para esse nome exato durante a primeira inicialização, usando um desafio HTTP que exige que o nome já resolva para esta máquina. Um registro que ainda não está no ar é, disparadamente, a forma mais comum de uma primeira instalação terminar em um erro confuso.
A implantação já vem com um script para mudar o domínio depois, então isso é recuperável, não fatal. O que não é recuperável em um único comando é tudo o que vem depois: o certificado é reemitido, todo botão de pagamento e URL de webhook que você distribuiu aponta para o nome antigo, um endereço Lightning é um nome em um domínio e se move junto com ele, e qualquer plugin de loja precisa ser reconfigurado. Escolha um nome que você esteja disposto a manter no papel timbrado por anos, e prefira um subdomínio de um domínio que você já publica a um novo que descreva o que a máquina faz.
Depois, escreva as regras de firewall enquanto nada ainda está escutando. Quatro portas, e somente quatro. O checkout é, por necessidade, um endpoint HTTPS público — o navegador de um cliente precisa alcançá-lo — e a porta 80 fica aberta porque a renovação do certificado a usa. A porta peer-to-peer do Lightning só é necessária se você quiser que outros nós consigam abrir canais em sua direção, o que o passo 05 vai argumentar que você quer. A porta peer-to-peer do Bitcoin não precisa ficar aberta de jeito nenhum: o seu nó faz conexões de saída perfeitamente bem, e abri-la para entrada só facilita que a encontrem.
ufw default deny incoming
ufw allow 47222/tcp # administrative SSH, moved off 22
ufw allow 80/tcp # ACME HTTP-01 challenge and the redirect
ufw allow 443/tcp # the checkout
ufw allow 9735/tcp # Lightning peer-to-peer, only if you want inbound channels
ufw enable
ufw status numbered
Duas notas de recursos antes de continuar. Dê swap à máquina, se ela não tiver nenhum — o download inicial de blocos é a hora mais faminta por memória deste projeto, e 4 GB de RAM com 2 GB de swap se comporta bem melhor do que 4 GB sozinhos. E confira a conta de disco do passo 01 contra o plano que você realmente pediu, porque um nó que enche o volume no meio da sincronização não falha educadamente; ele corrompe o próprio índice e recomeça.
fallocate -l 2G /swapfile && chmod 600 /swapfile
mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
df -h / # confirm the volume matches step 01
A implantação oficial não é um docker-compose.yml que você edita. É um gerador: você descreve a implantação que quer em variáveis de ambiente, e um script monta o arquivo de compose a partir de uma biblioteca de fragmentos — um para o Bitcoin Core, um para o indexador, um para o PostgreSQL, um para a aplicação BTCPay, um para cada implementação Lightning, um para o proxy reverso, e uma longa cauda de extras opcionais. Esse é um design melhor do que parece à primeira vista, porque as atualizações regeneram o arquivo, em vez de pedir que você mescle as mudanças de outra pessoa com as suas. Isso também significa que o bloco de ambiente abaixo é a configuração real da sua implantação, e vale a pena guardá-lo no mesmo lugar que as suas outras anotações de infraestrutura.
Clone o repositório e exporte o ambiente. Cada linha abaixo mapeia diretamente para uma decisão do passo 01: o host name é o domínio que você apontou no passo 02, o fragmento de armazenamento é a janela de poda que você escolheu, e a variável do Lightning é uma implementação, ou é omitida por completo para um lançamento somente on-chain.
mkdir BTCPayServer && cd BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
export BTCPAY_HOST="pay.example.com" # exactly the name you pointed in step 02
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="clightning" # or "lnd", or omit for on-chain only
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s" # ~50 GB pruned window
export BTCPAY_ENABLE_SSH=true
export LETSENCRYPT_EMAIL="you@example.com"
. ./btcpay-setup.sh -i
Dois detalhes nesse bloco merecem uma frase cada. O ponto no início de . ./btcpay-setup.sh -i não é um erro de digitação — o script recebe source, em vez de ser executado, então o ambiente que ele define permanece no seu shell, e os comandos auxiliares funcionam depois. E o nome do fragmento de armazenamento é sensível à versão: o gerador já lançou variantes que podam para cerca de 100, 50, 25 e 5 GB, sob nomes que foram ajustados entre versões. Leia a lista de fragmentos no repositório que você acabou de clonar, em vez de confiar em um valor copiado de um post de blog, incluindo este.
O instalador vai levar alguns minutos, baixar um monte de imagens, obter o certificado e iniciar tudo. Depois começa a espera: o nó precisa baixar e validar a cadeia antes de a loja conseguir confirmar um pagamento, o que leva horas, não minutos, mesmo podado, porque a poda descarta blocos depois de validá-los, e não em vez de fazer o trabalho. A interface web fica disponível imediatamente e vai mostrar um aviso de sincronização. Não emita uma fatura de verdade até que ele suma.
./bitcoin-cli.sh getblockchaininfo | grep -E 'blocks|headers|verificationprogress|pruned'
docker ps --format '{{.Names}}\t{{.Status}}'
Uma instância nova não tem usuários, e a primeira conta a se registrar se torna a administradora. Até você reivindicá-la, qualquer um que alcançar a URL pode fazer isso — e a URL não é secreta: no instante em que o certificado foi emitido, o hostname foi publicado nos logs públicos de certificate transparency, que são indexados e varridos continuamente por gente procurando exatamente isso. Abra o site e registre-se antes de qualquer outra coisa, depois confira o Server Settings e confirme que o registro não está aberto a estranhos. Essa é uma janela de cinco minutos que as pessoas deixam aberta por dias porque a loja "ainda não está no ar".
Dois fragmentos opcionais valem a pena conhecer enquanto você ainda está na configuração. Um adiciona um serviço oculto do Tor, para que o checkout fique alcançável também em um endereço onion v3, além do da clearnet — útil para clientes que preferem não resolver o seu domínio, e a mesma ideia do guia de serviço onion. Outro adiciona uma segunda criptomoeda. Os dois são configurados da mesma forma, adicionando à variável additional-fragments e rodando o script de configuração de novo; o gerador reconstrói o arquivo de compose e reinicia só o que mudou.
Crie uma loja, e depois tome a única decisão desta página que realmente importa. O BTCPay vai oferecer duas formas de conectar uma carteira Bitcoin: conectar uma já existente, ou deixar que ele gere uma nova e guarde a seed no servidor. A primeira é somente leitura, e é essa que você quer. A segunda transforma uma máquina pública, exposta à internet, em uma carteira quente guardando o seu faturamento, e nenhuma quantidade de hardenização torna isso uma boa troca para uma máquina cujo trabalho inteiro é ser alcançável por estranhos.
O mecanismo por trás da recomendação é elegante o bastante para valer a pena entender. Carteiras modernas são hierárquicas: uma seed deriva uma árvore de chaves, e existe uma chave pública estendida — uma xpub, ou sua variante zpub para segwit nativo — a partir da qual todo endereço de recebimento em uma conta pode ser calculado sem nenhuma capacidade de assinar. Entregue isso à loja, e ela consegue gerar um endereço novo para cada fatura, observar a cadeia em busca de pagamentos para cada um, e mostrar o saldo a você. Ela não consegue mover um único satoshi. A metade privada fica na sua carteira, ou no seu dispositivo de hardware, e nunca viaja.
Então: abra o Sparrow, o Electrum, ou o aplicativo de desktop da sua hardware wallet, crie uma nova conta dedicada a esta loja, e exporte a chave pública estendida dela. Nas configurações de carteira da loja, escolha conectar uma carteira existente, cole a chave, e confira os primeiros endereços que o BTCPay deriva contra os que a sua carteira mostra. Se baterem, o caminho de derivação está certo e a conexão está feita. Se não baterem, você escolheu o tipo de script errado — a diferença entre uma xpub e uma zpub é a diferença entre dois conjuntos de endereços inteiramente separados.
Ele não consegue gastar, e esse é o objetivo — mas consegue enumerar. Quem quer que a obtenha consegue derivar todo endereço que a conta algum dia vai usar e, portanto, ler todo pagamento que ela já recebeu e vai receber, enquanto você a usar. Essa é uma divulgação permanente e irrevogável do faturamento da sua loja, e é por isso que a conta que você conecta deve ser dedicada à loja, e não aquela que guarda as suas economias. Trate a chave como confidencial, mantenha-a fora de capturas de tela e tickets de suporte, e, se ela vazar, mude a loja para uma conta nova em vez de torcer para que dê certo.
Agora as configurações de fatura, que são onde uma loja é de fato ajustada. Expiração vem por padrão em cerca de quinze minutos, e é um travamento de taxa de câmbio, não um limite técnico: é por quanto tempo você está disposto a manter um preço em moeda fiduciária contra um ativo volátil. Encurte para um mercado volátil, alongue se os seus clientes forem lentos. Confirmações decidem quando uma fatura conta como paga — confirmação zero é instantânea e adequada para um café, uma confirmação é o padrão comum, e seis é para valores em que uma hora de espera sai mais barata que a alternativa. Tolerância de subpagamento permite aceitar uma fatura que chega com uma fração a menos, o que acontece o tempo todo quando a carteira de um cliente deduz a própria taxa do valor em vez de somá-la; um pequeno percentual aqui elimina uma categoria inteira de e-mail de suporte.
Depois teste com dinheiro de verdade, não com testnet. Emita uma solicitação de pagamento de um valor irrisório, pague-a a partir de uma carteira no celular, e observe a fatura passar de nova para em processamento e depois para paga. Essa única transação prova que o nó está sincronizado, que o caminho de derivação está certo, que o provedor de câmbio funciona, que o certificado é válido em um navegador móvel, e que o dinheiro caiu em uma carteira que você controla. Nada mais prova as cinco coisas de uma vez.
O Bitcoin on-chain paga uma fatura de $400 lindamente e uma de $4 mal: o cliente espera por uma confirmação e paga uma taxa que pode ser uma fração perceptível da compra. O Lightning inverte os dois — liquidação em cerca de dois segundos, taxas medidas em frações de centavo — e é por isso que uma loja que vende coisas pequenas precisa dele, e uma que vende coisas grandes talvez não. Se você configurou uma implementação Lightning no passo 03, o daemon já está rodando e o BTCPay já se conectou a ele; as configurações da loja só precisam habilitar o Lightning como método de pagamento.
Qual implementação você escolheu tem consequências que vale a pena nomear. Core Lightning é a opção conservadora e leve, com uma arquitetura de plugins limpa. LND é a mais amplamente implantada, e tem o maior ecossistema de ferramentas de gerenciamento ao redor dela. Também existe agora um terceiro tipo de opção — um daemon leve que terceiriza o gerenciamento de canais para um provedor de serviço, mantendo as chaves na sua máquina — o que troca um pouco de independência pelo desaparecimento de tudo o que está nos próximos três parágrafos. Essa é uma escolha legítima para uma loja que quer o Lightning, mas não quer se tornar uma operadora de nó; é simplesmente uma troca diferente, não uma troca de graça.
Um canal Lightning guarda uma quantia fixa de dinheiro, dividida entre as duas pontas. Quando você abre um canal e o financia, todo esse dinheiro fica do seu lado — o que é capacidade para enviar, e exatamente zero capacidade para receber. Uma loja precisa do oposto. Então um nó recém-financiado com três canais saudáveis ainda pode falhar em cada fatura recebida, e a falha se parece com um erro de roteamento, não com um erro de configuração. Este é o motivo isolado mais comum para um checkout Lightning auto-hospedado parecer quebrado no primeiro dia.
Existem três formas honestas de conseguir capacidade de entrada, e elas não são mutuamente exclusivas. Você pode abrir canais de saída e depois gastar através deles — comprando algo, pagando uma fatura, movendo dinheiro para uma exchange — o que empurra o seu saldo para o outro lado e converte capacidade de envio em capacidade de recebimento. Você pode pedir a um nó bem conectado que abra um canal em sua direção, o que é um pedido normal na comunidade Lightning e gratuito, à parte a taxa on-chain do peer. Ou você pode comprar liquidez de entrada de um dos vários serviços que a vendem, o que custa um pequeno percentual e leva minutos, não semanas. Não há recomendação de afiliado nesta página, e não vai haver; escolha pela reputação e pelo preço atual.
Uma vez que você já pode ser pago, dois recursos transformam o nó em uma vitrine de loja. Um endereço Lightning — no mesmo formato de um endereço de e-mail, no seu próprio domínio — permite que qualquer um te envie dinheiro a partir de qualquer carteira moderna sem que uma fatura precise existir antes, o que é o mecanismo de doação e gorjeta mais amigável que existe em qualquer lugar. E o QR code na página de checkout pode oferecer os dois trilhos ao mesmo tempo, então um cliente com carteira Lightning paga em segundos, e um cliente sem uma paga on-chain, a partir da mesma tela e sem exigir nenhuma decisão de você.
Antes de chegar o primeiro pagamento Lightning, faça o passo de backup que precisa acontecer agora, não depois. Cada implementação guarda um pequeno arquivo descrevendo o estado atual dos seus canais — o LND o chama de backup estático de canal — e é esse o artefato que permite recuperar fundos se a máquina for perdida. Ele muda toda vez que um canal é aberto ou fechado, então copie-o para fora da máquina automaticamente, não manualmente. Leia o aviso do passo 06 antes de presumir que o seu arquivo noturno já cobre isso, porque para o Lightning, especificamente, ele não cobre.
Escolha a menor superfície de checkout que caiba no que você já tem. Uma solicitação de pagamento é um link que você envia para alguém — sem necessidade de site, e a forma mais rápida de faturar um cliente. Um aplicativo de ponto de venda transforma a mesma instância em um caixa com lista de produtos, o que funciona a partir de um celular em uma banca de mercado. Um botão de pagamento é um trecho de HTML para um site estático. Um plugin de loja adiciona o Bitcoin como método de pagamento a uma loja de verdade e atualiza o status do pedido de volta automaticamente. E a API REST emite faturas, informa o estado delas e chama um webhook quando uma é paga, o que é a integração que envelhece melhor porque não depende de nada além de HTTP e um segredo compartilhado.
Qualquer uma que você escolher, configure o webhook e depois teste se ele dispara. Uma fatura que é paga e nunca notifica a sua aplicação é o modo de falha que ninguém pega, porque tudo parece correto dos dois lados isoladamente: o dinheiro chegou, o cliente viu uma página de confirmação, e o pedido fica sem ser cumprido. Envie a si mesmo um webhook de fatura-paga de propósito, confirme que o seu endpoint o recebeu, e verifique a assinatura em vez de confiar no payload — esse endpoint é público, e qualquer um pode postar nele.
Este é o único aviso nesta página que pode custar dinheiro, não tempo, e a própria documentação do projeto o afirma nas mesmas palavras: estado antigo de canal do Lightning é tóxico. Restaurar a cópia da noite passada de um banco de dados de canais e deixar o nó rodar significa transmitir um estado que a sua contraparte já substituiu — o que o protocolo trata como uma tentativa de trapaça, e pune concedendo a ela o saldo inteiro do canal. Então o arquivo é certo para o banco de dados da loja, a configuração e o histórico de faturas, e não é um plano de recuperação para canais. Copie o backup estático de canal para fora da máquina continuamente, mantenha o mais recente, e, se algum dia você restaurar um servidor inteiro a partir de um arquivo, faça isso sabendo que o lado do Lightning precisa do procedimento de recuperação documentado, não de uma restauração direta.
Com isso entendido, a rotina é curta. A implantação já vem com um script de backup que arquiva os volumes e despeja o banco de dados, pulando os dados da blockchain, e ele aceita uma senha para que o arquivo seja criptografado antes de sair da máquina. Rode-o em um timer, e depois envie o resultado para uma máquina em outra jurisdição, do jeito que o guia de backups descreve — um repositório somente-anexação vale os dez minutos extras aqui, porque um servidor de pagamento comprometido não deveria conseguir apagar o registro do que processou.
cd ~/BTCPayServer/btcpayserver-docker
export BTCPAY_BACKUP_PASSPHRASE="a long passphrase you keep elsewhere"
./btcpay-backup.sh # archives volumes + database, skips the chain
# then ship the archive offsite, and keep the channel backup separately
As atualizações vêm a seguir, e uma máquina de pagamento é a única em que "atualizar depois, de propósito" é a política correta. A implantação tem o próprio script de atualização, que regenera o arquivo de compose e baixa as novas imagens; rode-o quando você tiver lido as notas de lançamento, não quando um cron job achar que é hora. Faça o arquivo primeiro. Suba uma versão de cada vez. E mantenha a versão anterior anotada, porque um rollback que você consegue fazer em um minuto é o que torna tudo isso de baixo risco.
./btcpay-update.sh # deliberate, after reading the release notes
df -h / # the check that should be an alert, not a habit
Por fim, configure um alerta e um lembrete. O alerta é sobre uso de disco — um nó de blockchain é o único processo na máquina que cresce por conta própria, e um volume cheio derruba o checkout de um jeito lento de diagnosticar, porque mais nada mudou. Dispare-o em oitenta por cento, não em noventa e cinco. O lembrete é mensal, e serve para abrir a loja e olhar duas coisas: se as faturas ainda estão sendo pagas, e se os canais Lightning que você abriu ainda estão vivos. Um processador de pagamento falha silenciosamente, e a forma como você descobre é um cliente te contando que não conseguiu pagar.
Auto-hospedar o processador é uma melhoria real e específica, e não é um passe de mágica. Cinco coisas continuam verdadeiras depois que tudo acima está feito, e conhecê-las é a diferença entre uma defesa de verdade e uma história reconfortante.
O livro-razão do Bitcoin é público e permanente. Remover o gateway removeu o banco de dados privado de uma empresa; não criptografou a cadeia. Todo pagamento que a sua loja recebe é visível para qualquer um que conheça um endereço, para sempre, e endereços se agrupam: uma carteira que combina dois pagamentos em um único gasto acabou de contar ao mundo que aqueles dois clientes pagaram a mesma loja. Essa é uma propriedade do ativo, não do software, e é o motivo pelo qual um negócio com uma exigência real de privacidade também olha para o Monero.
O hostname do checkout é publicado no instante em que passa a existir. Os logs de certificate transparency são públicos e indexados continuamente, então o nome que você escolheu no passo 02 é descobrível mesmo que você nunca link para ele. É por isso que a conta de administrador precisa ser reivindicada nos primeiros minutos, não na primeira semana, e por isso que a página de login merece uma senha forte e um segundo fator desde o primeiro dia.
A saída para o fiduciário é onde a identidade volta. Nada nesta pilha exige que você se identifique para aceitar um pagamento. Converter o resultado em dinheiro bancário quase sempre exige, porque essa conversão acontece em uma exchange ou corretora regulada. Auto-hospedar move a exigência de identidade do ponto de venda para o ponto de saída — uma melhoria genuína na exposição, e não a mesma coisa que a ausência dela.
As suas obrigações de declaração não se moveram junto com o servidor. Onde um negócio é registrado e onde o seu dono mora decidem o que é devido e o que precisa ser declarado. A jurisdição da máquina que emite as faturas não entra nessa conta. Na maioria dos lugares, receber cripto por bens ou serviços é renda comum, pelo valor do dia, e aliená-la depois é um evento separado, de novo. Uma instância auto-hospedada é um registro melhor do que uma conta de processador que você pode perder — não é uma forma de não ter um registro.
Não existem estornos, e isso corta dos dois lados. Um pagamento confirmado é definitivo, e é exatamente essa propriedade que torna a fraude contra um comerciante quase impossível e o motivo de a taxa ser zero. É também o motivo de um cliente insatisfeito não ter mecanismo nenhum além da sua boa vontade. Publique uma política de reembolso, use o recurso de repasse para honrá-la, e entenda que você assumiu o trabalho de resolução de disputas que o percentual costumava pagar.
O que você realmente comprou, com precisão: o dinheiro chega em uma carteira da qual só você pode gastar, ninguém pode impedir a venda, ninguém fica com uma parte, e a lista de quem pagou o quê a você existe só em uma máquina que você aluga sem nome nenhum atrelado. Essa é uma afirmação restrita, e é uma afirmação real. Ela só vale o que custa se o passo 06 estiver feito — um processador de pagamento auto-hospedado sem uma restauração testada não é uma melhoria de negócio, é um ponto único de falha segurando o seu faturamento.
| Nível | Mensal | Recursos | O que ela roda com folga |
|---|---|---|---|
| Sentinel | $3.90 | 2 vCPU · 4 GB · 120 GB · 1 Gbps | Um nó podado de 25–50 GB com Lightning. Adicione swap; fique de olho no disco. |
| Garrison | $7.90 | 4 vCPU · 8 GB · 240 GB · 1 Gbps | Um nó podado de 100 GB, Lightning e anos de margem. O padrão. |
| Ravelin | $16.90 | 8 vCPU · 16 GB · 480 GB · 2.5 Gbps | O mesmo, mais uma segunda cadeia ou uma loja movimentada com plugins. |
| Bulwark | $32.90 | 16 vCPU · 32 GB · 960 GB · 5 Gbps | Um nó arquivístico com espaço para continuar crescendo. Só se você precisar do histórico. |
O BTCPay, o indexador e o PostgreSQL juntos são alguns gigabytes e quase nenhuma CPU depois que o nó está sincronizado; uma loja recebendo cem pagamentos por dia não vai incomodar nem o menor plano em termos de processamento. Onde os planos diferem é no disco, e o disco é decidido inteiramente pelo passo 01. A sincronização é a única hora genuinamente pesada do projeto — ela é limitada por IO, não por CPU, e é por isso que o NVMe importa aqui e a quantidade de núcleos não. A banda é ilimitada em todos os planos, então um nó Lightning publicamente alcançável não custa nada extra para rodar.
A primeira pessoa a se registrar em uma instância nova se torna a administradora, e o hostname foi publicado nos logs de certificate transparency no instante em que o certificado foi emitido. Registre-se nos minutos seguintes ao fim da instalação, e depois confirme no Server Settings que o registro não está aberto a estranhos.
Deixar o servidor gerar a carteira é um clique só, e coloca a seed em uma máquina cujo trabalho é responder a estranhos. Em vez disso, conecte uma chave pública estendida: a loja observa, deriva e reconcilia, e não consegue gastar. Guarde a metade privada em uma carteira ou em um dispositivo de hardware.
Um banco de dados de canais de ontem descreve um estado que sua contraparte já substituiu. Trazê-lo de volta pode entregar a ela o saldo inteiro do canal como penalidade. O arquivo noturno cobre a loja; os canais precisam do caminho de recuperação documentado e de um backup de canal copiado continuamente.
Financiar um canal te dá capacidade de enviar, não de receber. Um nó novo com dinheiro dentro ainda falha em todo pagamento recebido, e o erro parece um problema de roteamento. Consiga liquidez de entrada antes de anunciar a opção Lightning, não depois da primeira reclamação.
Conecte uma conta de três anos a um nó podado, e as transações antigas dela nunca aparecem, porque os blocos que as continham foram descartados. Nada está quebrado, e nada avisa isso. Dê à loja uma conta recém-criada, ou rode arquivístico.
Um nó é o único processo que cresce por conta própria, e um disco cheio corrompe o índice em vez de pausar educadamente — o que significa recomeçar o download do zero. Faça a conta do passo 01 contra o plano que você pediu, e configure o alerta em oitenta por cento, não em noventa e cinco.
Onze perguntas que surgem ao construir isso — começando pelas duas que decidem se você deveria sequer construir isso.
É genuinamente gratuito, e o formato disso importa mais do que o preço. O BTCPay Server é um software de código aberto lançado sob uma licença permissiva e mantido por uma fundação, não por uma empresa com meta de faturamento; não há taxa por transação, não há percentual, não há volume mínimo, não há conta para abrir e não há contrato para assinar, porque não há contraparte nenhuma — você está rodando um programa no seu próprio servidor, do mesmo jeito que roda um servidor web. O que você paga em vez disso é real, mas diferente: alguns dólares por mês pela máquina, uma noite para configurar, e a obrigação permanente de manter atualizado um serviço que lida com pagamentos. A comparação que as pessoas deveriam realmente fazer não é "grátis contra um por cento". É "uma tarefa operacional que é sua contra uma dependência que não é", e a resposta honesta é que uma loja recebendo vinte pagamentos por ano provavelmente é mais bem servida por algo hospedado, enquanto uma loja recebendo vinte por semana sai mais barato e mais livre por aqui.
Você guarda, e o mecanismo vale a pena entender, não apenas confiar nele. A configuração recomendada dá ao BTCPay uma chave pública estendida de uma carteira que você já controla. A partir dessa chave, o servidor consegue derivar um endereço de recebimento novo para cada fatura e observar a cadeia em busca de pagamentos para ele — e não consegue construir um gasto válido, porque a metade privada nunca sai da sua carteira. O dinheiro se move do cliente direto para um endereço que só você pode varrer; nada fica guardado no servidor, então não há nada para reter, congelar, ou perder em uma invasão. O BTCPay também vai oferecer para gerar uma carteira para você e guardar a seed no servidor, o que é conveniente e é a única configuração contra a qual este guia argumenta, para qualquer coisa que guarde faturamento de verdade: isso transforma uma máquina pública, exposta à internet, em uma carteira quente. O Lightning é a exceção genuína — os fundos de canal precisam estar ativos para rotear — e é por isso que o saldo do Lightning deve ser tratado como um caixa, não como um cofre.
Depende inteiramente de uma decisão, e a faixa é de duas ordens de grandeza. Um nó Bitcoin Core arquivístico guarda todo bloco já minerado: folgadamente acima de 700 GB em 2026, e somando cerca de 50 GB por ano, então precisa de um plano dimensionado para isso, e vai continuar precisando de mais. Um nó podado valida cada bloco exatamente da mesma forma, e depois descarta os antigos, mantendo uma janela móvel — o gerador de implantação vem com fragmentos que podam para cerca de 100, 50, 25 ou 5 GB, e qualquer coisa a partir de 50 GB é uma escolha de produção perfeitamente séria para um comerciante. Some cerca de 10 a 20 GB para o indexador, o banco de dados, o nó Lightning e o sistema operacional, e a conta fecha: um plano de 120 GB roda uma implantação podada de 25–50 GB, um plano de 240 GB roda uma de 100 GB com anos de margem, e o arquivístico quer 960 GB. Escolha podado, a menos que você tenha um motivo específico para não fazer isso; o modelo de segurança é idêntico.
Em parte, e vale a pena saber exatamente onde está a linha. A pilha pode ser apontada para um nó Bitcoin que você já roda em outro lugar — uma máquina no mesmo tailnet, ou uma atrás de um túnel — e esse é um arranjo totalmente suportado, que poupa uma segunda cópia da cadeia caso você já tenha feito o trabalho em o guia do nó Lightning. O que você não pode fazer com sensatez é rodar um processador de pagamento contra o nó público de outra pessoa, e o motivo não é licenciamento, mas privacidade e confiança: quem quer que responda às suas consultas aprende todo endereço que a sua loja está observando, o que é o mesmo que aprender o seu faturamento, e também pode mentir sobre se uma fatura foi paga. Existe uma terceira opção à qual as pessoas recorrem — usar uma instância BTCPay hospedada, administrada por terceiros — e é uma forma perfeitamente razoável de começar. Só tenha claro que isso move os dados da loja para um operador que consegue vê-los, que é a maior parte do motivo de auto-hospedar.
Não, e é inteiramente razoável deixá-lo de lado no primeiro dia. Somente on-chain é uma configuração completa e funcional: as faturas são pagas, o cliente espera por uma confirmação, a loja recebe. O que o Lightning compra é a diferença entre "cerca de dez minutos e uma taxa que dói em valores pequenos" e "dois segundos e uma fração de centavo", que é a diferença entre um checkout que funciona para uma fatura de $400 e um que também funciona para uma de $4. O custo é que o Lightning é um segundo daemon, com fundos próprios, modos de falha próprios e disciplina de backup própria — incluindo o problema de liquidez de entrada do passo 05 e o aviso de estado tóxico do passo 06. Uma ordem sensata é lançar on-chain, confirmar que todo o pipeline funciona com dinheiro de verdade, e depois adicionar o Lightning como um segundo projeto deliberado, em vez de encaixá-lo na mesma noite.
Qualquer carteira que consiga exportar uma chave pública estendida para uma única conta — Sparrow, Electrum, BlueWallet, ou uma hardware wallet através de uma dessas — e a parte importante não é a marca, mas sim que seja uma conta dedicada, e não aquela que guarda as suas economias. Dois motivos. O primeiro é privacidade, e é permanente: uma chave pública estendida é um índice mestre de todo endereço que ela algum dia vai derivar, então quem quer que a obtenha consegue enumerar todo pagamento que aquela conta já recebeu e vai receber. Dar à loja a própria conta significa que um vazamento expõe só o faturamento da loja, e nada mais. O segundo é operacional: uma conta dedicada torna a renda da loja legível sem que você precise fazer perícia em um histórico misturado, e torna a varredura para armazenamento frio uma decisão única e sem graça. Uma hardware wallet guardando a chave privada, com a loja vigiando a pública, é o arranjo a que se deve mirar.
Sim, com a ressalva de que cada cadeia adicional é um nó adicional inteiro, com o próprio disco, o próprio tempo de sincronização e a própria manutenção. O gerador suporta uma segunda e uma terceira criptomoeda diretamente, e existe uma integração com Monero disponível como um fragmento adicional — a mesma implantação passa então a apresentar ao cliente uma escolha de trilhos no checkout. O que as pessoas subestimam é a conta de recursos: cada cadeia que você habilita é mais um daemon indexando mais um livro-razão no mesmo volume, e duas cadeias em um plano dimensionado para uma é assim que uma máquina de pagamento fica sem disco em um domingo. Se o Monero é importante para a sua loja, leia primeiro o guia do nó Monero e considere dar a ele a própria máquina; um processador de pagamento que fica fora do ar porque um daemon não relacionado encheu o disco é pior do que um que só aceita Bitcoin.
Quatro formas, em ordem crescente de quanto software você já tem. Se você não tem nada, o BTCPay já vem com uma página hospedada de ponto de venda e de solicitação de pagamento que você pode enviar como um link — o suficiente para faturar um cliente ou receber pagamentos em uma banca de mercado sem site nenhum. Se você tem um site estático, um botão de pagamento é um trecho de HTML. Se você tem uma loja de verdade, existem plugins mantidos para as plataformas de e-commerce mais comuns, que transformam o Bitcoin em mais um método de pagamento no checkout, com o status do pedido atualizado de volta automaticamente. E se você tem a sua própria aplicação, a API REST emite faturas, informa o estado delas, e chama um webhook que você especificar quando uma é paga — que é a integração que envelhece melhor, porque não depende de nada além de HTTP. Comece com uma solicitação de pagamento, prove que o dinheiro chega, depois integre.
Para on-chain, não, e essa é a recompensa silenciosa do design somente leitura: as moedas nunca estiveram no servidor. Os endereços são derivados de uma chave pública, então uma instalação nova com a mesma chave pública estendida redescobre todo pagamento; o que você perde em uma falha total é a configuração da loja e o seu histórico de faturas, que é para isso que serve o script de backup. O Lightning é uma resposta genuinamente diferente e merece a própria frase: os fundos de canal estão vivos, o estado do canal muda a cada pagamento, e restaurar uma cópia antiga desse estado pode custar o saldo do canal inteiro, porque publicar um estado já substituído é exatamente o que o protocolo pune. Então a postura correta é assimétrica. Faça backup do banco de dados e da configuração em uma agenda, criptografe-o, envie-o para algum lugar que não seja esta máquina — e trate o backup estático de canal do Lightning como um artefato separado, copiado continuamente, em vez de uma linha no arquivo noturno.
Não, e vale a pena ser direto sobre isso, porque o oposto é presumido silenciosamente. Remover o processador de pagamento remove um intermediário, uma taxa e uma parte que poderia congelar os seus fundos. Isso não muda o que você deve, a quem, ou se uma venda é tributável — essas coisas decorrem de onde você e o seu negócio estão, não de onde fica o servidor ou qual software emitiu a fatura. Na maioria das jurisdições, receber criptomoeda por bens ou serviços é renda comercial comum, pelo valor do dia em que foi recebida, e aliená-la depois é um evento separado, de novo; o fato de o registro agora viver no seu próprio banco de dados, em vez do de um processador, não torna isso opcional, e uma instância auto-hospedada é, na prática, uma trilha de auditoria melhor do que uma captura de tela de uma conta que você não tem mais. Onde o ganho de privacidade honesto está é mais estreito e real: nenhum terceiro guarda uma lista contínua dos seus clientes e valores. Pergunte a um contador na sua própria jurisdição sobre o resto.
Sim — uma instância BTCPay é uma aplicação web comum, com um banco de dados comum e um daemon de blockchain comum, e não há nada na política de uso aceitável que a trate diferente de uma loja ou de um blog. As notas práticas são sobre recursos, não sobre política: um nó em sincronização é pesado em disco e em IO no primeiro dia, e depois fica quase ocioso, a banda é ilimitada em todos os planos, então um nó Lightning público não é medido, e as portas de entrada para conexões de peer são suas para abrir. A parte que se alinha com o resto do site é a simetria: a conta não precisa do seu nome legal, a fatura é paga em Monero, Bitcoin ou Lightning, e a máquina que agora conhece cada cliente seu é alugada de uma empresa que não sabe quem você é. Um processador que você auto-hospeda em uma conta identificada moveu o livro-razão, não a exposição.
Garrison — 4 vCPU, 8 GB e 240 GB de NVMe por $7.90 ao mês, em Helsinque, Estocolmo, Oslo ou Reykjavík. Suficiente para um nó Bitcoin podado, um daemon Lightning, o indexador e a loja, com margem para anos. Sem e-mail no cadastro, sem documento de identidade, e sem empresa nenhuma guardando a lista de todo mundo que já pagou você.
Última revisão · 2026-10-12 · Fontes · Documentação do BTCPay Server (implantação com Docker, fragmentos de armazenamento, backup e restauração, configurações da loja), documentação do Bitcoin Core sobre poda, documentação da implementação Lightning sobre backups estáticos de canal · Cadência · anualmente
This guide is one spoke of a larger series. The pillar walks the three privacy layers end to end — the sibling spokes below dive into the specifics.
Three independent layers — signup, payment, network — explained, legal context included, common mistakes flagged.
Your own LN node — bitcoind + LND or Core Lightning, on a VPS.
O seu próprio monerod — completo ou podado, RPC atrás de um túnel, transmissão via Tor.
Deploy your own MCP server on a no-KYC VPS — TLS, streamable HTTP, OAuth.
Host an MCP server with no ID — the privacy stack, crypto-paid.
Hospedagem privada, construída no Norte.