PRIMEIROS PASSOS

Documentação

Instale, receba pagamentos e cuide do seu servidor.

Chegou agora? Siga os tutoriais passo a passo →

Requisitos do VPS

Use um VPS Linux novo com acesso root, não um servidor que já hospede sites ou bancos de dados. Não precisa de Docker, compilador nem nós de blockchain.

VPSMínimo
Uso leve
Recomendado
CPU1 vCPU2 vCPU
RAM2 GB4 GB
SSD20 GB60 GB

O mínimo é um ponto de partida para uso leve com imagens mínimas de Ubuntu/Debian, não uma garantia de desempenho. O espaço em disco inclui Linux; deixe pelo menos 3 GiB livres antes da instalação, além de espaço para atualizações, histórico e backups.

O instalador nativo exige x86-64, systemd 247+ e Python 3.9+. ARM64 e Alpine/OpenRC não estão incluídos.

Versões do Linux e notas sobre capacidade
  • Ubuntu 22.04+ ou Debian 12+; Mint 21+ e Pop!_OS 22+.
  • Fedora 42+; Rocky, AlmaLinux, RHEL, Oracle Linux ou CentOS Stream 9–10.
  • openSUSE Leap 16+ ou Tumbleweed; Arch, Manjaro ou EndeavourOS.

Escolha uma versão mantida pelo fornecedor. Requisitos maiores do sistema operacional têm prioridade: openSUSE Leap 16 exige mais de 40 GB de disco.

Mais redes e faturas simultâneas podem exigir mais CPU e RAM. Um VPS maior não elimina os limites de RPC. Os fluxos de instalação têm testes automatizados; os testes completos em VPS novos ainda não cobrem todas as distribuições.

Instalar

Aponte estes nomes de host padrão para o seu VPS ou escolha os seus:

  • merchant.example.com: console
  • pay.example.com: checkout
  • api.example.com: API

Use registros somente DNS durante a instalação. Abra TCP 80/443 nos dois firewalls e mantenha o SSH acessível. Nunca exponha PostgreSQL nem o aplicativo nas portas 5432/8080.

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh)

A instalação verifica os downloads e configura PostgreSQL, Nginx, HTTPS e os serviços. Prefere contêineres? Veja a instalação opcional com Docker.

Verifique primeiro ou retome a instalação

Inspecione o instalador. Adicione --check ao comando para verificar a compatibilidade sem instalar, ou --help para ver as opções.

Retome o progresso salvo sem substituir chaves nem configurações:

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh) --resume

Domínios base adicionais podem usar os mesmos nomes de serviço. Registros IPv6 também devem apontar para este VPS. Ative um proxy da Cloudflare somente após a validação do domínio.

Configuração inicial

  1. Insira o login HTTP Basic. Crie sua conta de administrador, escolha o idioma e o fuso horário e confira a licença e política de privacidade.
  2. Confira Configurações → Conexões de redes. Use provedores de reserva independentes e saudáveis que permitam rastrear pagamentos.
  3. Crie um projeto e depois a primeira loja dele.
  4. Faça um backup das carteiras do projeto. Na loja, selecione as redes aceitas e os tokens verificados.
  5. Defina moeda, confirmações, validade, margem e tolerância. Confira seu saldo de créditos antes de criar faturas.

Os QR solicitam todo o valor pendente. A tolerância só aceita diferenças a menor; as confirmações continuam obrigatórias.

Valores de stablecoins

Novas cotações de stablecoins reconhecidas são arredondadas para cima: 1.321 USDC → 1.33 USDC, mesmo com tolerância zero. Mínimo: 0.01 token.

Faturas existentes, saldos e valores restantes de pagamentos parciais mantêm sua precisão exata. Outros tokens e tokens personalizados preservam a precisão normal.

Ativação automática

O cadastro do administrador registra automaticamente sua conta de créditos usando seu email, com um crédito de boas-vindas único equivalente a 10 USD . Não precisa de código de ativação.

Criar uma fatura. A ativação pendente é repetida automaticamente; reconectar nunca concede crédito de novo.

Dados de acesso e valores padrão

Seu login Basic Auth fica salvo em /root/whollycrypto/config/setup-credentials.txt. Ele é separado do email e da senha do console.

Novos projetos herdam a moeda e o fuso horário padrão do sistema; as lojas usam a moeda do projeto. Os fusos horários de contas existentes são gerenciados separadamente em Configurações → Conta.

whollycrypto welcome mostra a URL do seu console.

Modo lojista ou operador

Instalações novas a partir de 7.0.0 escolhem um modo ao configurar o primeiro administrador. Isso não pode ser desfeito; mudar de modo exige uma nova instalação. Instalações anteriores à 7 continuam no modo lojista, mesmo sem administrador.

Lojista: gerencie seus próprios projetos e lojas. Operador: hospede lojistas independentes em uma instalação e cobre sua própria taxa de processamento pré-paga. Seu próprio negócio está incluído sem uma taxa interna de operador.

Configurar lojistas hospedados
  1. Nós compartilhados, cotações, domínios, créditos da instalação e atualizações ficam no painel do operador.
  2. Abra Carteiras → Criar carteiras de recebimento para BTC, ETH e USDC/USDT na Ethereum. Faça backup das duas frases de recuperação independentes. Este projeto dedicado não pode emitir faturas de venda; uma loja de recebimento existente é preservada.
  3. Adicione um lojista com moeda de crédito, taxa e email do administrador. Compartilhe o convite e o Basic Auth do lojista em particular. Ele escolhe a senha. Nunca compartilhe o Basic Auth do operador.
  4. Os lojistas recarregam pelo seu checkout, ou você registra um ajuste de crédito com uma explicação. É preciso ter crédito antes de criar projetos ou lojas. Gerencie usuários e histórico de créditos em Lojistas → Gerenciar.

A configuração do operador pede um quarto endereço, como operator.example.com, e seu próprio usuário e senha de Basic Auth. Escolha seu rótulo, aponte o DNS para o VPS, verifique o DNS e ative HTTPS. O painel abre diretamente nesse endereço. Os endereços do lojista, do checkout e da API continuam separados.

Use o novo login Basic Auth do operador e depois seu email e senha de administrador. O Basic Auth do lojista não muda. A configuração pode ser retomada após erros de DNS ou certificado. Operadores que atualizam da 7.0.0 também concluem essa etapa; os endereços ativos existentes continuam disponíveis.

Taxas, isolamento e responsabilidade

A 3%, uma fatura de 100 EUR custa 3 EUR de crédito do lojista. Se a moeda de crédito for diferente, a cotação fiduciária no momento da criação é salva junto com a taxa.

O operador paga separadamente a taxa normal da instalação do Wholly Crypto. Os fundos do cliente não são divididos na blockchain. Compras de créditos não são cobradas de novo.

Só uma liquidação verificada automaticamente credita uma recarga. Abrir um checkout ou aceitar uma fatura manualmente não credita. Estornos criam lançamentos no livro-razão; uma recarga estornada que volte a ser recebida exige revisão do operador.

Crédito baixo do lojista hospedado pausa IPN, webhooks, envios de fundos e criação de novos projetos ou lojas. As faturas de clientes existentes e o recebimento continuam. Crédito baixo da instalação pode pausar automações de todos os negócios hospedados. Desativar um lojista também bloqueia o login e novas faturas, enquanto pagamentos antigos continuam sendo monitorados.

Esse isolamento é no aplicativo; não há um VPS separado para cada lojista. Lojistas não podem acessar projetos, carteiras, credenciais de API, exchanges ou créditos uns dos outros. O administrador do servidor pode acessar as chaves das carteiras quentes hospedadas. Avise os lojistas antes de cadastrá-los; use hospedagem confiável, backups independentes e capacidade adequada para cargas compartilhadas.

Finanças e convites do operador

Disponível no modo operador a partir de 7.1.0.

Carteiras e finanças

A partir de 7.2.0, Carteiras gerencia saldos de recebimento, endereços e backups; Envio de fundos gerencia envios e regras automáticas. Mantenha ETH para as taxas de tokens. Recargas dos lojistas acompanha as compras deles. Os créditos do cabeçalho pagam separadamente as taxas da instalação. Meu negócio abre seu próprio console em uma nova aba.

Abra Finanças para ver taxas recebidas, cobranças verificadas da instalação, margem estimada e créditos atuais dos lojistas. Filtre por data, lojista ou moeda do relatório; exporte CSV.

Os relatórios agrupam faturas pela primeira liquidação e refletem os estornos mais recentes das taxas. Saldos pré-pagos não são receita. Cobranças do seu próprio negócio ficam separadas. Cobranças pendentes ou cotações ausentes deixam as margens afetadas indisponíveis. As conversões usam as cotações fiduciárias atuais em cache; gás e custos operacionais não estão incluídos.

Convidar usuários ou redefinir senhas

Adicionar lojista cria um convite. A partir de 7.3.0, escolha um crédito inicial gratuito na moeda de crédito do lojista; zero é permitido. Isso não recarrega seu saldo de operador. Enviar convite por email vem marcado por padrão.

Configure seu provedor SMTP em Configurações → Email de convite primeiro, usando TLS ou STARTTLS. O teste de conexão não envia emails. Você também pode desmarcar o email e compartilhar o link em particular. Uma falha no email preserva a conta e o crédito; não crie o lojista de novo.

Para gerar outro link ou redefinir uma senha, abra Lojistas → Gerenciar → Contas de usuário. A aceitação SMTP não garante a entrega na caixa de entrada. Compartilhe o Basic Auth do lojista separadamente, nunca as credenciais do operador.

Convites duram 48 horas; redefinições, uma hora. Cada link funciona uma vez. Substitua ou revogue um link na mesma tela. Uma redefinição encerra as sessões existentes, mas mantém o 2FA ativado. O Basic Auth do lojista continua obrigatório.

API do operador

Automatize os lojistas hospedados com SDK 2.6.0 e Wholly Crypto 7.4.0+. Ative Operador → Configurações → API do operador, e crie uma chave de servidor com permissões limitadas.

Cadastro, permissões e novas tentativas seguras

Crie contas diretamente com senha ou envie convites. Gerencie usuários, projetos, lojas, taxas e créditos pré-pagos locais; consulte relatórios e assine eventos de ciclo de vida assinados. O consentimento de custódia no primeiro login, o 2FA e o isolamento entre lojistas continuam em vigor.

Cada gravação precisa de uma chave de idempotência salva. Concessões de crédito são ajustes locais de conta, não recargas da instalação. Segredos de carteiras, envios e configuração do servidor ficam fora desta API.

Use api.your-domain.com/v1/operator. Mantenha as chaves de operador no seu backend, nunca em um navegador nem com um lojista hospedado.

Referência e permissões da API do operador → · SDKs de PHP, Python e Node com exemplos →

Carteiras e tokens

Configurações → Tokens carrega primeiro 250 tokens e depois o restante do catálogo.

Projeto → Carteiras → Backup de todas exporta TXT ou HTML offline com busca e códigos QR. Ambos expõem chaves e frases de recuperação. Guarde uma cópia privada fora do servidor; nunca compartilhe nem envie esse arquivo.

Root pode acessar as chaves. Os guias de recuperação de carteiras explicam endereços de faturas, gás nativo e backups externos de Monero/Lightning.

Endereços salvos e saldos atualizados

Configurações → Catálogo de endereços: salve uma rede e um endereço. Moedas nativas e tokens correspondentes do CoinGecko aparecem automaticamente. É somente leitura e gerenciado pelo administrador; a aceitação no checkout não muda.

Os leitores de tokens cobrem 22 redes. Saldos privados e camadas de Bitcoin/CashTokens/Kaspa precisam de acesso ou indexadores separados. Leituras que falham mostram erros, não zeros.

Reúna os saldos das faturas em outra carteira com envios manuais ou automáticos de fundos. Transferências de tokens também precisam da moeda nativa da rede para as taxas.

Preço indisponível se refere a cotações, não a saldos.

Adicionar um token personalizado
  1. Loja → Formas de pagamento → EVM ou Solana → Token personalizado.
  2. Insira contrato/mint, nome e símbolo. Escolha preço fixo em USD ou cotação automática de DEX.

A rede e as casas decimais são verificadas. Preços do projeto não mudam as cotações existentes. Uma correspondência no catálogo por si só não ativa o checkout.

Preços automáticos

DEX Screener exige um pool com o contrato exato, $10,000 de liquidez e uma negociação na última hora. Os preços são atualizados a cada minuto; falhas ou preços com cinco minutos de idade bloqueiam novas cotações.

Preços de DEX podem ser manipulados; as verificações não são auditorias. Use tokens ERC-20 padrão ou SPL clássicos confiáveis. Token-2022 e extensões não são compatíveis. Sem um pool adequado, use preços fixos.

Moeda e fuso horário

Configurações → Sistema → Padrões regionais define a moeda e o fuso horário de novos projetos e o fuso horário de novas contas. Configurações e créditos existentes não mudam; a moeda do painel ainda pode ser alterada.

Fuso horário pessoal: Configurações → Conta → Editar usuário.

Criar uma fatura

Use Formas de pagamento → Escolher para esta fatura para limitar as redes e os tokens aceitos. Todas as formas de pagamento da loja mantém os valores padrão.

  1. Abra Projeto → Faturas → Criar fatura.
  2. Escolha a loja, a moeda fiduciária e o valor.
  3. Compartilhe o link do checkout. Seu cliente escolhe uma rede e um token disponíveis e vê o QR, o valor restante, a validade e as confirmações.

Teste um pagamento pequeno com cada forma antes de começar a operar. Confira a fatura antes de entregar um pedido: uma URL de retorno não comprova o pagamento.

Para integrações, verifique IPN/webhooks assinados e confirme o status pela API de faturas. Trate eventos duplicados como o mesmo evento.

API: filtre payment_methods por chain_slug e asset_tickers. Opções inativas são ignoradas; sem correspondências, são usados os padrões da loja. Filtrar só por rede inclui todos os ativos ativos dela. Símbolos compartilhados exigem IDs dos ativos. Carteiras e cotações continuam necessárias.

Valores e confirmações

Scanner offline? As faturas mantêm as formas configuradas enquanto a detecção aguarda. Confira as APIs compatíveis em Conexões de redes; estar saudável não significa ser compatível com o scanner. Padrão: dois provedores independentes.

Carteiras e cotações continuam necessárias. Os serviços Monero/Lightning precisam emitir solicitações de pagamento.

Erros de API/MCP incluem error.details.payment_methods. SDK 2.4.0 adiciona explicações seguras: PHP getPaymentMethodIssues(), Python payment_method_issues, Node paymentMethodIssues. Referência de erros →

As cotações cripto são arredondadas para cima e incluem a margem da loja. Uma fatura com preço fiduciário não converte a cripto recebida em saldo bancário.

Zero confirmações liquida o pagamento na detecção, sem a proteção das confirmações da rede. Pagamentos nativos EVM são detectados como transferências diretas. Revise pagamentos incomuns ou incertos em Requer atenção.

APIs de rastreamento

Confira Conexões de redes para ver APIs compatíveis, histórico completo e provedores independentes. Atualizar o histórico a partir de um nó bruto leva tempo. Todas as APIs de recebimento →

Pagamentos, saldos e manutenção compartilham os limites dos provedores. Verificações ociosas ficam menos frequentes. Faturas antigas mantêm o monitoramento de pagamentos tardios e reorganizações, até uma vez por hora após atualizar o histórico. Avisos WSS disponíveis complementam o rastreamento HTTP. Fechar o checkout nunca interrompe a detecção. Nós públicos continuam tendo limites; Wholly Crypto não opera nós.

Faturas de valor zero

Bloqueadas por padrão. Ative Lojas → Fatura → Permitir faturas de valor zero para permitir totais zero manuais ou por API. Elas são concluídas imediatamente, sem pagamento, endereço de recebimento, transação ou taxa de processamento.

Checkout

Loja → Checkout: cores, logos, formas de pagamento, links, tamanhos de fonte de Intro/Outro e visibilidade do nome do projeto ou da loja. Lojas novas herdam o design da loja padrão. As alterações são salvas automaticamente.

As prévias não podem receber pagamentos. Não há HTML/CSS/JavaScript personalizado.

Teste a demonstração.

IPN e webhooks

IPN envia cada evento de fatura para a URL da loja ou para o ipn_url da fatura. Webhooks enviam eventos selecionados. Ambos enviam por POST o mesmo retrato em JSON.

Quando devo entregar o pedido? Para o processamento por eventos, use event_type = invoice.settled com status = settled. Verifique a fatura atual e seu pedido e entregue uma única vez. payment.received sozinho não basta.

Status e eventos: exemplos de Ethereum e Solana

status é o status da fatura na criação do evento; event_type indica o que aconteceu.

  • Exemplo de Ethereum: payment.received + processing, depois invoice.settled + settled.
  • Exemplo de Solana: já é definitivo quando detectado, então payment.received e invoice.settled ambos incluem settled.

Qualquer fluxo pode ocorrer em outras redes. São eventos distintos, não necessariamente dois pagamentos. Podem compartilhar sequence mas ter valores diferentes de event_id . A ordem de entrega não é garantida; não exija processing primeiro.

Status e dados de notificação
Status da faturaSignificado
newAguardando pagamento
processingPagamento parcial ou aguardando finalidade
settledAceito pelas regras da fatura ou manualmente
expiredPrazo encerrado; o monitoramento tardio pode continuar
invalidO pagamento precisa de revisão ou foi rejeitado
cancelledCancelado, não reembolsado

Eventos: invoice.created, payment.received, invoice.processing, invoice.settled, invoice.expired, invoice.invalid, invoice.cancelled. Tabela completa de eventos e regras de exceção →

amount_status: none, partial, paid, overpaid. paid inclui a tolerância, não a finalidade. timing_status: on_time ou late. resolution: automatic, manually_settled ou manually_invalidated. Aplique sua política de exceções quando requires_review for true.

invoice_id corresponde à resposta da API. amount, currency e order_id descrevem seu pedido original. payment_info adiciona transferências, valores cripto exatos, cotação/margem/tolerância fixadas e cotações indicativas. Dados do cliente e metadados são privados.

paid_chain, paid_asset, paid_payment_method_id, paid_asset_amount, paid_asset_amount_received e settlement_exchange_rate resumem a liquidação. Permanecem fixos; evidências ou histórico ausentes ficam em null. Para recebimentos posteriores use payment_info ou a API de pagamentos.

Use strings decimais. Nunca combine ativos nem trate fundos não confirmados como ausentes. Trate exceções explicitamente; um aviso sozinho nunca autoriza a entrega nem o reembolso. Recargas internas de gás verificadas não são pagamentos de clientes e não acionam payment.received.

Segredos de assinatura, novas tentativas e histórico de entregas

Segredos de assinatura separados: Loja → IPN assina as entregas IPN, incluindo o valor personalizado da fatura para ipn_url. Cada endpoint em Loja → Webhooks tem seu próprio segredo, mostrado ao criá-lo ou rotacioná-lo.

Ambos usam Wholly-Signature e o mesmo verificador do SDK, mas precisam do segredo correspondente, não de uma chave de API. Rotacionar o segredo IPN não altera os segredos dos webhooks.

Verifique o corpo sem alterações, o carimbo de tempo e o escopo de projeto e loja. Salve de forma durável e retorne HTTP 2xx. Um worker consulta a fatura atual pelo host de API configurado e entrega uma única vez dentro de uma transação de banco de dados. Cabeçalhos não são assinados; use a identidade assinada no corpo da versão 2.

Por eventos: elimine duplicatas do valor assinado event_id, depois filtre invoice.settled. Por estado com SDK: agrupe projeto + invoice_id + sequence, depois verifique o status independentemente do tipo de evento. Não adicione um filtro de eventos após agrupar. Ambos precisam de proteção separada contra duplicatas por pedido.

Novas tentativas preservam o corpo e o ID do evento originais. Revisões antigas não devem sobrescrever as mais novas. IPN faz até oito tentativas; novas tentativas de webhooks são opcionais. Crédito baixo pausa as entregas, não os pagamentos.

Loja → IPN / Webhooks → Histórico → Detalhes mostra o corpo salvo e o resultado. Os dados expiram após 90 dias. Um reenvio não comprova a liquidação.

Dados completos, tabela de eventos e exemplos do receptor →

Conversão por exchange

Envie ativos compatíveis para Kraken, Binance ou Coinbase. Mantenha a moeda ou converta os depósitos creditados. A moeda fiduciária permanece na exchange.

Os mínimos de depósito se aplicam por transação, não por envio de fundos. Depósitos abaixo do mínimo interrompem o plano. Consolide primeiro os saldos pequenos na sua própria carteira; há taxas de rede adicionais.

Conecte e escolha uma rota
  1. Configurações → Exchanges: conecte uma chave dedicada, confira os saldos e conceda acesso aos projetos. Sem permissões de saque; restrinja a chave ao IP do seu VPS.
  2. Projeto → Envio de fundos: verifique ativo, rede, endereço e contrato do token. Para cada rede e token, escolha outra carteira ou uma exchange.

Os mercados são atualizados a cada dois minutos. Só depósitos identificados e creditados podem ser convertidos; mercados desatualizados interrompem novas ordens. Uma reserva de 1% do ativo de origem fica na exchange para taxas e arredondamentos, separada dos créditos de processamento.

Manter valor mínimo reserva moedas ou tokens em todo o projeto após os envios automáticos. É separado do gatilho; zero não reserva nada. As taxas usam o excedente. Os envios manuais não mudam.

Retome transferências incertas; nunca as substitua. As carteiras continuam reservadas até a confirmação ou até expirar uma cotação não usada. Envios grandes precisam de lotes.

Aplicam-se custódia da exchange, KYC, limites regionais e taxas. Sem pagamentos bancários nem alavancagem. Crédito baixo pausa novas conversões; ordens enviadas continuam sendo conciliadas.

Créditos de processamento

Você continua recebendo pagamentos quando os créditos acabam. Lojas existentes mantêm faturas, checkout e monitoramento de pagamentos. A falta de uma conexão de faturamento verificada ou a suspensão da conta são situações diferentes e podem bloquear novas faturas.

Continua disponívelPausado sem crédito utilizável
Faturas, checkout e confirmaçõesIPN/webhooks, incluindo novas tentativas
Carteiras, saldos e backupsEnvio de fundos: envios, gás, reembolsos e novas conversões em exchanges
Relatórios, APIs de leitura e configurações existentesCriação de projetos e lojas
Verificação de atualizações e recuperação de atualizações interrompidasInstalação de novas versões

Recarregue pelo ícone de créditos. Após verificar a recuperação, as automações ativadas são retomadas, incluindo regras que enviam fundos. Desative as regras que você não quer retomar.

Recargas automáticas de créditos

Abra Recarga automática depois de Solicitações. Escolha uma carteira de recebimento com backup, limite de acionamento, valor da compra, limite diário e teto de taxa de rede. Autorize e salve. Começa desativada.

Use BTC, ETH ou USDC/USDT na Ethereum quando oferecidos. Endereços que enviam tokens precisam de ETH; esta regra não fornece o gás que faltar. Operadores usam carteiras de recebimento dedicadas; lojistas hospedados pagam ao operador deles.

A recarga aprovada pode ser executada enquanto o crédito baixo pausa o envio de fundos. Só o serviço receptor confirma o crédito. Uma compra automática é executada por vez. Desativar interrompe o trabalho não enviado, não as transações já enviadas.

Recuperar um pagamento automático

Em Recarga automática, use Verificar pagamento. Retome o mesmo pagamento válido ou encerre uma transferência Ethereum com falha verificada e pause a regra. Pagamentos pendentes ou incertos continuam retidos para evitar envios duplicados. Uma cotação vencida não comprova uma falha.

Taxas e restauração do acesso completo

O 1% padrão usa o valor fiduciário original da fatura liquidada. Os pagamentos cripto do cliente não são divididos.

As taxas continuam se acumulando até gerar saldo negativo. Cubra o valor negativo e restabeleça crédito utilizável acima do limite de tolerância da sua conta. Alterações de saldo normalmente aparecem em 10–15 segundos com uma conexão saudável.

Instalar atualizações exige crédito verificado acima de zero, mesmo com uma margem de tolerância para automações. Recargas nunca instalam atualizações automaticamente.

Notificações pausadas não consomem tentativas. As entregas retidas são retomadas; a validade normal continua se aplicando. Concilie eventos perdidos pela API de faturas.

Se o operador desativar as taxas de processamento, não se aplicam novas taxas nem restrições de crédito. Cobranças anteriores permanecem no histórico. Uma instalação não vinculada pode configurar projetos e lojas, mas precisa de faturamento verificado para emitir faturas. Faturas já emitidas continuam sendo monitoradas.

Relatórios

Os gráficos de receita e os filtros ficam acima das abas: Projetos e lojas, Faturas, Carteiras e Envios de fundos. Busque abaixo. Projetos e lojas inclui exportações CSV. Datas personalizadas cobrem até 366 dias. Carteiras usam saldos em cache.

Como funcionam os valores dos relatórios
  • A receita mostra os valores das faturas liquidadas antes de taxas e reembolsos, usando as datas de liquidação. Não é o saldo das carteiras nem o lucro.
  • As conversões usam cotações atuais em cache, não cotações contábeis históricas. Os totais na moeda original continuam disponíveis se faltarem cotações.
  • Os gráficos de status usam as datas de criação das faturas. Os valores de Requer atenção mostram os problemas atuais não resolvidos.

Assistentes de IA · MCP

Acesso opcional limitado ao projeto em api.example.com/mcp. Consulte pagamentos ou aprove a criação de faturas. Configuração e permissões do MCP →

SDKs

Use nossos SDKs oficiais para criar faturas, consultar pagamentos e verificar IPN/webhooks.

SDK de PHP

PHP 7.4+

Adicione pagamentos cripto ao seu aplicativo PHP com Composer.

composer require whollycrypto/php-sdk
GitHub e exemplos ↗

SDK de Python

Python 3.10+

Conecte seu aplicativo ou backend Python sem dependências de execução.

python -m pip install whollycrypto
GitHub e exemplos ↗

SDK de Node.js

Node.js 22+

JavaScript ou TypeScript, um pacote npm com tipos integrados.

npm install whollycrypto
GitHub e exemplos ↗

Use o domínio de API da sua instalação e mantenha as chaves de API no servidor. Todos os SDKs têm licença MIT.

Envio de fundos

Mova os fundos recebidos para o destino que você escolher. Gerencie regras e histórico em Projeto → Envio de fundos.

Envie moedas nativas em 29 redes; Monero continua somente leitura. Tokens: ERC-20 verificados e SPL clássicos. Envios manuais e automáticos usam as mesmas proteções.

Envio manual: prepare, revise e aprove

BTC, EVM, SOL e TRX se juntam a 18 adaptadores nativos. Use um provedor capaz de transmitir transações. ZEC só aceita endereços transparentes; ADA preserva saídas de tokens; DOT usa Asset Hub; HBAR precisa de um relay. Destinos de saída que exigem memo/tag/comentário precisam de uma carteira externa.

  1. Abra Projeto → Carteiras → ativo → Enviar. Escolha uma entrada do catálogo de endereços ou insira um destino. Confira o endereço completo e a rede.
  2. Escolha um valor exato ou enviar o disponível, depois um nível de taxa. Para tokens compatíveis, Usar ETH do projeto para gás (ou a moeda nativa da rede) pode fornecer as taxas que faltarem a partir do mesmo projeto e rede.
  3. Clique em Preparar transferência. Revise origens, destino, valor, taxas máximas e qualquer alocação de gás. Aprovar e enviar autoriza este plano; só prepará-lo não envia nada.

O fornecimento de gás, as confirmações e o envio de tokens continuam em segundo plano após a aprovação. Acompanhe Atividade de transferências, mesmo após fechar a janela. A transmissão não é uma confirmação.

Manter ETH na carteira do projeto: 0 não adiciona uma reserva; não gasta todo o seu ETH. 0.005 mantém pelo menos 0.005 ETH para depois, então você precisa de fundos adicionais para este fluxo. As regras automáticas salvas não mudam.

Configuração de envios automáticos
  1. Abra Configuração de envios automáticos → ativo → Configurar. Escolha um endereço de carteira ou um destino de exchange compatível, não ambos.
  2. Defina o mínimo de envio e Manter valor mínimo. Exemplo: acionar com 100 USDC, manter 20 USDC, enviar até 80 USDC. A reserva se aplica a todo o projeto, não a cada endereço.
  3. Para tokens, revise Usar ETH do projeto para gás e insira um Limite diário de fornecimento de fundos. Ative Envio automático, depois Salvar regra e confirme. Só abrir Configurar não ativa nada.

O limite diário restringe o gás nativo alocado por regra de token em uma janela móvel de 24 horas. €1 pode ser um limite inicial para uso leve, não um custo garantido nem uma cobrança diária. Transações de fornecimento de fundos também têm taxas. Taxa de rede máxima % pode limitar a soma das taxas de fornecimento e transferência.

As verificações são executadas automaticamente. Só endereços aptos que têm tokens recebem gás; os vazios não. Um endereço sem fundos suficientes e abaixo do mínimo de envio aguarda. Explicação dos limites de gás →

Boas práticas e transferências pausadas
  • Faça backup das carteiras e teste uma transferência pequena. Envie os tokens antes de esvaziar as moedas nativas. O ETH de outra parte do projeto precisa chegar primeiro a cada endereço com tokens; o gás não usado permanece nas suas carteiras.
  • Use saldos recentes, provedores saudáveis e fundos nativos suficientes. Regras automáticas precisam de uma carteira ativa com backup e do ativo habilitado em uma loja habilitada. Um saldo baixo de créditos de processamento pode pausar os envios.
  • Em Atividade de transferências, revise o progresso, Fornecimento de gás e os links do explorador. Se o resultado for incerto, atualize a mesma transferência; não crie outra para substituí-la. Retome só após revisar o motivo e os limites.

Envio desativado? Confira whollycrypto transfers status. Revise cada regra ativada antes de whollycrypto transfers enable: aplica-se ao servidor inteiro e pode executar imediatamente as regras salvas. Interromper etapas futuras não reverte transmissões.

Domínios

Configurações → Sistema: escolha Gerenciar ou Adicionar domínio. Salve, confira o DNS e publique. Hosts sem alterações pulam as verificações DNS/SSL.

Domínios da loja

Loja → Básico: escolha hosts ativos de lojista/pagamento/API. Os links priorizam loja → loja padrão → sistema; nomes retirados usam alternativas. Configure os hosts do SDK separadamente. Novas tentativas assinadas preservam os links originais.

HTTPS é automático. Ative Cloudflare após configurar; Let's Encrypt continua ativo.

Lista de verificação do Cloudflare
  • Use Full (strict), não Flexible; não precisa de chave de API.
  • Desative o cache e os desafios de navegador/bots para console, checkout e API.
  • Permita /.well-known/acme-challenge/ na porta 80 sem redirecionamentos nem desafios para as renovações.

As verificações consultam o DNS autoritativo e verificam a origem: Direta ou Cloudflare. Visitantes podem ter DNS antigo em cache.

Salvar e excluir no console usa POST desde 5.6.2; não precisa de uma exceção “Not GET or POST”. O login e o CSRF continuam ativos. Em api.*, permita os métodos documentados da API pública.

Segurança da conta

Configure 2FA em Configurações → Conta. Usuários limitados a projetos usam Minha segurança no rodapé. Confirme sua senha, escaneie o QR ou a chave TOTP e insira um código de seis dígitos.

Experimente Verifyr Authenticator para iOS ou Android, ou outro aplicativo TOTP padrão. Guarde os códigos de recuperação de uso único separados da sua senha. Mantenha a proteção HTTP Basic ativada.

Recuperação e aparência

Substituir códigos ou desativar 2FA exige sua senha e um autenticador ou código de recuperação não usado. As outras sessões são encerradas. Mantenha os relógios do telefone e do servidor sincronizados; 2FA não protege um servidor comprometido.

O ícone de tema alterna entre Claro → Suave → Escuro e lembra a escolha deste navegador. Os temas do checkout das lojas são separados.

Segurança do servidor

  • Use chaves SSH e restrinja SSH a IPs confiáveis. Mantenha uma conexão de recuperação testada.
  • Ative o proxy da Cloudflare após configurar, usando Full (strict).
  • Em Configurações → Sistema → Restrições de IP de origem, permita IPs ou faixas confiáveis por nome de host ativo de merchant.* ou api.* . O IP atual do console deve continuar permitido.
  • Normalmente deixe pay.* aberto: clientes precisam pagar de qualquer lugar.
Cloudflare e recuperação de acesso

Opcionalmente adicione regras de acesso da Cloudflare. Isente os desafios de renovação HTTPS; evite desafios de login interativos na API e no checkout. O modo proxy sozinho não é uma restrição de IP.

Ficou sem acesso? Execute whollycrypto access-reset --domain merchant.example.com por SSH. Só esse nome de host é reaberto, em cinco segundos; a autenticação da conta continua ativada.

Corrigir HTTPS

whollycrypto ssl
whollycrypto ssl --fix

O primeiro comando verifica os certificados ativos. --fix repara os arquivos de suporte TLS e renova certificados ausentes ou próximos de vencer. Nginx precisa estar em execução; mantenha as portas 80/443 abertas.

Reemitir um certificado

Execute whollycrypto ssl --domain merchant.example.com --reissue para forçar a substituição. Aplicam-se limites de emissão. Se Cloudflare bloquear o desafio HTTP, use temporariamente somente DNS. Carteiras, autenticação e domínios não mudam.

Verificações diárias

  • Em Requer atenção, selecione faturas ou a página atual para marcar como revisadas, adicionar uma nota ou rastrear novamente. As decisões financeiras continuam individuais.
  • Monitore o espaço em disco, o atraso dos scanners e os nós alternativos independentes. Endpoints públicos não garantem capacidade.
  • Mantenha Linux atualizado, restrinja SSH e limite usuários e chaves de API aos projetos e permissões necessários.

As decisões precisam de um motivo. Reembolsos exigem uma transferência confirmada separada; mudar o status de uma fatura nunca envia dinheiro.

Atualizações e backups

Leia as notas da versão, depois use Configurações → Sistema → Atualizações de software ou a CLI. As atualizações verificam assinaturas, criam backups e verificam a saúde. O checkout pausa durante a instalação.

whollycrypto update --check
whollycrypto update

As atualizações aguardam até dois minutos pelas tarefas em segundo plano; o checkout continua online. Se o tempo se esgotar, os temporizadores são restaurados.

Atualizar a partir de 0.1.31 ou anteriores

Atualizador antigo bloqueado? Execute isto uma vez. Sua chave instalada verifica o assistente.

bash <(curl -fsSL https://releases.whollycrypto.com/update_wholly.sh)

Mantenha backups testados fora do servidor do PostgreSQL, da configuração, das chaves de criptografia das carteiras e das exportações de carteiras. Os arquivos locais de recuperação não são criptografados.

Restaure juntos os backups correspondentes de banco de dados e configuração. Nunca interrompa migrações nem execute binários antigos com bancos de dados mais novos. As regras de crédito continuam se aplicando.

Download alternativo pelo GitHub

A instalação e as atualizações tentam automaticamente o espelho oficial do GitHub. As verificações de assinatura, checksum e crédito continuam obrigatórias.

CLI do servidor

Comandos root por SSH.

whollycrypto status
whollycrypto doctor
whollycrypto backup
Todos os comandos
ComandoFinalidade
whollycrypto versionVersão instalada.
whollycrypto statusSaúde do aplicativo e do banco de dados.
whollycrypto logsÚltimas 80 linhas do log do aplicativo.
whollycrypto restartReiniciar e verificar a saúde.
whollycrypto doctorVerificações da instalação somente leitura.
whollycrypto doctor --fixReparar permissões gerenciadas e um link da CLI ausente.
whollycrypto htaccessRedefinir um login Basic Auth.
whollycrypto admin-resetRedefinir uma senha de administrador.
whollycrypto 2fa-resetRedefinir o autenticador de uma conta sem mudar a senha.
whollycrypto transfers status
whollycrypto transfers enable
whollycrypto transfers disable
Verificar, ativar ou pausar envios de todos os projetos. Ativar reinicia o aplicativo e pode executar imediatamente as regras salvas; exige confirmação. Atualizações preservam as pausas.
whollycrypto sslVerificar HTTPS; adicione --fix para reparar.
whollycrypto access-reset --domain HOSTRemover a restrição de IP de um nome de host.
whollycrypto update --checkBuscar atualizações assinadas.
whollycrypto updateFazer backup, atualizar e reiniciar.
whollycrypto backupArquivo somente para root em /root/whollycrypto/backups/releases/.
whollycrypto recoverRecuperar manutenção interrompida ou uma atualização sem mudança de esquema. Nunca restaura um banco de dados automaticamente.
whollycrypto resetEscolher um projeto, todos os projetos do negócio ou só reparar.
whollycrypto uninstall --check
whollycrypto uninstall
Pré-visualizar e depois remover o ambiente nativo. Banco de dados, chaves e backups são mantidos.
whollycrypto welcomeURL e links do console.
whollycrypto --helpComandos; adicione --help depois de um para ver as opções dele.
Diagnosticar problemas de instalação

As verificações são somente leitura e retornam um código de saída diferente de zero quando algo requer atenção. --fix só repara permissões gerenciadas e um link da CLI ausente. Nunca muda o faturamento, exclui dados nem reinicia serviços.

Escolher o alcance da redefinição
whollycrypto reset
# Preview without changing anything:
whollycrypto reset --scope business --check
whollycrypto reset --scope project --project YOUR_PROJECT_IDENTIFIER --check

Escolha um projeto, todos os projetos do negócio ou só reparar. Redefinir projetos apaga permanentemente os projetos, lojas, registros de carteiras e histórico de pagamentos selecionados. Só reparar verifica e corrige as permissões gerenciadas e o link da CLI.

Primeiro desative os projetos selecionados, resolva pagamentos e transferências abertos e mova os saldos conhecidos das carteiras. Contas, domínios, nós, créditos, identidade de faturamento e modo da instalação são mantidos. Carteiras de recebimento do operador e registros de crédito hospedados são protegidos. Isso não reabre o assistente de configuração.

Uma redefinição destrutiva exige uma confirmação digitada e cria um backup de recuperação verificado antes de apagar. Guarde também um backup das carteiras fora do servidor: endereços antigos ainda podem receber fundos, mas projetos excluídos deixam de acompanhá-los. Saldos em cache não comprovam que as carteiras estão vazias.

Remover uma instalação nativa
whollycrypto uninstall --check
whollycrypto uninstall

Interrompe checkout, API e workers; remove arquivos de execução e integração gerenciada com o servidor após backup e confirmação digitada. Pagamentos ou transferências pendentes bloqueiam a remoção. Os arquivos são movidos para o backup de recuperação em vez de apagados.

Banco de dados, configuração, chaves e backups são mantidos. Pacotes compartilhados de Nginx/PostgreSQL e certificados TLS não são alterados. O comando mostra um comando de recuperação offline; não execute uma instalação nova sobre os dados preservados.

Os comandos de redefinir/remover são para instalações nativas em VPS, não Docker nem Umbrel. Para contêineres, use os comandos de backup e parada da sua integração; preserve os volumes. Nenhum dos comandos destrutivos aceita --yes.

Redefinir o login Basic Auth
whollycrypto htaccess

Selecione um usuário, escolha nome e senha e confirme. Isso redefine a primeira solicitação de login do navegador, não sua conta do console. Outros usuários e credenciais de API não mudam.

Redefinir uma senha de administrador
whollycrypto admin-reset

Escolha um administrador por email e confirme a nova senha. Sessões e bloqueios de login da conta são removidos; restrições de IP permanecem.

Redefinições normais preservam o 2FA. Se você perdeu tanto o autenticador quanto os códigos de recuperação, execute explicitamente whollycrypto admin-reset --email admin@example.com --reset-2fa. Configure 2FA novamente após entrar.

Precisa do banco de dados, não do aplicativo nem da senha antiga. Outras contas, carteiras e permissões não mudam; contas desativadas continuam desativadas.

Redefinir 2FA

Perdeu o autenticador e os códigos de recuperação? Escolha uma conta como root.

whollycrypto 2fa-reset
# Or select the account directly:
whollycrypto 2fa-reset --email user@example.com

Remove sessões, autenticador e códigos de recuperação. Entre com a senha existente e configure 2FA novamente. Permissões, carteiras e Basic Auth não mudam; contas desativadas continuam desativadas.

Exige o banco de dados, não o aplicativo nem créditos. Sem interação: --email e --yes.

Senhas geradas e automação

Enter gera uma senha em /root/whollycrypto/config/credential-resets/: privada, sem criptografia e utilizável após o sucesso. Senhas inseridas manualmente não são salvas.

whollycrypto htaccess --user admin --new-user operator
whollycrypto admin-reset --email admin@example.com

Sem terminal, especifique a conta existente mais --generate ou --password-file /root/private-password.txt, e --yes. Arquivos de senha devem pertencer a root, com modo 600. Nunca coloque senhas em comandos nem variáveis de ambiente.

--yes só pula a confirmação. Termine primeiro a recuperação de atualizações interrompidas; alterações simultâneas na conta interrompem as redefinições.