Entenda o fluxo e os requisitos de pagamento
Se quer saber como aceitar pagamentos em criptomoedas num site Next.js, comece pelo fluxo, não pelo código. Um checkout com criptomoedas costuma ter 4 etapas: criar um pedido, apresentar uma solicitação de pagamento, monitorizar a blockchain e só marcar o pedido como pago após a verificação.
Parece simples. Raramente é.
«Aceitar criptomoedas» num site Next.js não significa que a sua aplicação guarda moedas. Na maioria dos casos, o site cria um pedido de pagamento para o cliente, que envia os fundos a partir de uma carteira. Depois, um serviço de pagamentos ou o seu próprio backend confirma a transferência. Um bom checkout também precisa de um prazo de validade, porque uma cotação justa às 10:00 pode já não o ser 20 minutos depois.
Também precisa de decidir que redes e ativos vai aceitar. Uma loja que aceita USDT em Ethereum, Polygon e BNB Chain não tem o mesmo funcionamento de um site que só aceita BTC numa rede. A escolha da rede afeta as taxas, o tempo de confirmação e o tipo de carteira de que o cliente precisa. Se aceitar uma rede errada, o pagamento pode chegar a um destino onde não conseguirá associá-lo a um pedido.
Há um teste prático a fazer: um cliente que nunca usou o site consegue concluir o checkout em menos de 2 minutos? Se não, o fluxo precisa de ser melhorado. Uma carteira, um montante, um endereço claro e uma página de estado igualmente clara. É esse o nível de simplicidade que as pessoas esperam.
Escolha um fornecedor de pagamentos em criptomoedas ou uma integração com carteira
Pode criar um checkout com criptomoedas de 3 formas gerais. A primeira é usar o checkout alojado de um fornecedor. A segunda é integrar uma carteira diretamente, ligando a aplicação a uma biblioteca de carteiras. A terceira é usar um gateway de pagamentos que faz a ligação entre o utilizador e a blockchain. Cada opção tem um custo de implementação diferente; a escolha certa depende de querer rapidez, controlo ou ambos. Para perceber como integrar um gateway de pagamentos cripto no Next.js, comece por comparar as responsabilidades que o fornecedor assume com as que ficam a cargo do seu backend.
Um checkout alojado costuma ser a opção mais rápida de implementar. Cria uma fatura, encaminha o cliente para uma página alojada e o fornecedor trata da deteção do pagamento. Uma integração direta com carteira pode ficar mais bem integrada no produto, mas geralmente implica mais código, mais casos especiais e mais responsabilidade pela confirmação dos pagamentos. Um gateway fica entre as duas partes e costuma ser uma escolha prática para o comércio, pois pode criar faturas, acompanhar confirmações e disponibilizar webhooks.
Antes de escolher, verifique 5 aspetos: as moedas e as redes aceites, o suporte a webhooks, o prazo de validade das faturas e a quantidade de código de backend que o fornecedor espera que escreva. Se está a comparar opções para uma loja, o guia sobre gateways de pagamentos em criptomoedas para comércio eletrónico é um bom ponto de partida, pois aborda a mesma decisão do ponto de vista de quem vende. Um freelancer que fatura a clientes pode dar mais importância a faturas e ligações de pagamento do que uma loja online; por isso, também é relevante considerar os gateways de pagamentos em criptomoedas para freelancers.
Uma observação: se um fornecedor disser que aceita «todos os principais ativos», peça uma lista concreta. «Todos» é vago. «BTC, ETH e USDC em 3 redes» é uma informação que permite tomar uma decisão.
Prepare o projeto Next.js para os pagamentos
Comece por organizar bem a aplicação. Num projeto Next.js com App Router, coloque a lógica de pagamentos em rotas do servidor ou em server actions e mantenha as chaves secretas fora do cliente. Uma estrutura simples pode incluir 1 página de produto, 1 formulário de checkout, 1 rota de API para criar faturas e 1 rota de webhook para eventos de pagamento.
As variáveis de ambiente devem incluir a chave secreta do fornecedor de pagamentos, o segredo do webhook e os valores de API públicos que podem ser expostos no navegador. Não coloque a chave secreta num componente do cliente. Este erro pode comprometer toda a conta e é um dos que pode sair caro rapidamente.
Se o fornecedor disponibilizar um SDK, instale-o apenas na camada do servidor. Se fornecer endpoints HTTP simples, também funciona. A ideia principal é a mesma: o navegador pede ao backend Next.js que crie uma solicitação de pagamento e o backend comunica com o fornecedor. O navegador nunca deve decidir que um pedido está pago.
Para equipas que estão a passar de pagamentos com cartão, a estrutura não é muito diferente de um fluxo com Stripe; mudam apenas as etapas de verificação. Se essa comparação ajudar, leia como migrar do Stripe antes de definir as rotas da API. Uma rota de API chega para um protótipo; 3 ou 4 podem ser preferíveis quando acrescentar novas tentativas, reembolsos e histórico do estado dos pedidos.
Crie a interface de checkout em Next.js
A interface de checkout pode ser um cartão de produto, uma página de carrinho ou um simples botão para iniciar o pagamento. Num componente de cliente do Next.js, o botão costuma enviar os dados do pedido para a rota do servidor, aguardar a resposta e, em seguida, redirecionar o cliente ou apresentar instruções para a carteira.
Mantenha o formulário curto. O nome do produto, o montante, o e-mail e, talvez, uma nota sobre o pedido costumam ser suficientes. Se pedir 9 campos, é provável que mais pessoas desistam. Se pedir 3, o processo será mais rápido. Um checkout que demora 30 segundos é mais agradável do que um que demora 3 minutos, mesmo que ambos terminem no mesmo pagamento.
O botão de pagamento deve ter um rótulo claro: «Pagar com criptomoedas». Não «Continuar» ou «Avançar». Esses rótulos escondem o custo da etapa seguinte. Quando o cliente clicar no botão, contacte o backend, obtenha a solicitação de pagamento e apresente o endereço da carteira, o código QR e o montante na mesma página.
Uma solução útil é manter o resumo do pedido visível enquanto as instruções de pagamento são carregadas. Assim, o cliente vê o artigo exato e o montante correspondente. Isso reduz a confusão quando o valor do pagamento é fixado em USD, mas pago com um ativo volátil.
Gere endereços de pagamento, faturas ou ligações de pagamento
Cada pedido deve corresponder a 1 solicitação de pagamento única. Pode ser um endereço de carteira, uma ligação de pagamento ou um objeto de fatura criado pelo fornecedor. Reutilizar o mesmo endereço para todos os clientes dificulta a reconciliação e pode gerar trabalho de apoio ao cliente que seria fácil evitar.
Numa loja pequena, pode gerar um novo endereço para cada pedido e guardar na base de dados o endereço, o montante esperado, o ativo e a data de validade. Num fluxo gerido por um fornecedor, este poderá devolver um ID de fatura e uma ligação de pagamento alojada. Em qualquer dos casos, associe a solicitação de pagamento ao ID do pedido antes de a apresentar ao cliente.
Apresente os detalhes de forma simples: ativo, rede, montante e destino. Um código QR é útil, mas não deve substituir o texto. Algumas carteiras não leem bem os códigos QR e alguns utilizadores preferem copiar e colar manualmente. Um endereço claro continua a ser essencial.
Se precisar de aceitar pagamentos para serviços ou faturas através de um endereço, os padrões são semelhantes aos descritos no artigo sobre gateways de pagamentos em criptomoedas para freelancers. Uma ligação de pagamento costuma ser mais prática para pedidos pontuais; um registo de fatura dedicado é melhor quando precisa de guardar o histórico de pagamentos e enviar lembretes.
Confirme os pagamentos na blockchain e atualize o estado do pedido
É na confirmação do pagamento que muitas equipas perdem o rigor. Não marque um pedido como pago só porque a carteira mostra uma transferência pendente. Não confie apenas no navegador. O seu backend deve verificar a transação diretamente na rede ou receber um webhook assinado do fornecedor de pagamentos. Para saber como verificar pagamentos em criptomoedas com webhooks, valide a assinatura do evento e confirme os dados do pagamento antes de alterar o estado do pedido.
O fluxo habitual é simples. O fornecedor deteta o pagamento, envia um webhook para a rota Next.js e o servidor verifica a assinatura antes de alterar o estado do pedido. Se implementar esta etapa por conta própria, terá de verificar o hash da transação, o endereço de destino, o ativo, o montante e o número de confirmações exigido pela sua política. Um pagamento pode parecer válido antes de ser definitivo.
Use um modelo de pedidos com 3 estados: pendente, confirmado e pago. «Pendente» significa que a solicitação existe. «Confirmado» significa que a rede detetou o pagamento e que este tem confirmações suficientes. «Pago» significa que a aplicação atualizou o processamento do pedido ou o controlo de acesso. Mantenha estes estados separados para que a equipa de apoio saiba se o cliente está à espera, se o pagamento foi verificado ou se o produto já foi entregue.
Se usar webhooks, valide-os sempre. O artigo sobre como verificar webhooks assinados da Payora é útil mesmo que não use PHP, porque a ideia é a mesma: rejeitar mensagens que não provem que foram enviadas pelo fornecedor. Esta verificação, por si só, pode bloquear eventos falsos de pagamento.
Trate dos casos especiais, da segurança e dos testes
Um checkout com criptomoedas pode falhar de mais formas do que um checkout com cartão. Uma cotação pode expirar. O cliente pode enviar fundos pela rede errada. Uma carteira pode enviar um montante ligeiramente inferior. O navegador pode ser atualizado a meio do processo. Cada situação precisa de uma resposta que indique ao utilizador o próximo passo.
As cotações expiradas não devem ficar sem resolução. Se uma ligação de pagamento for válida durante 15 minutos, mostre claramente o temporizador e crie uma nova solicitação quando o prazo terminar. As transferências pela rede errada precisam de uma via de apoio, porque o dinheiro pode existir, mas não no local esperado pela aplicação. Os pagamentos insuficientes podem ser aceites, rejeitados ou sinalizados para análise, mas a política deve estar definida antes do lançamento, não depois da primeira reclamação.
A segurança não é opcional. Guarde as chaves secretas apenas em variáveis de ambiente do servidor. Verifique as assinaturas dos webhooks. Armazene apenas os dados de pagamento de que precisa. Se registar IDs de transação, oculte qualquer informação sensível que não seja necessária para a depuração. Teste numa testnet ou com as ferramentas de sandbox do fornecedor antes de aceitar pagamentos reais. Para uma lista prática de verificações, consulte como testar um pagamento em criptomoedas antes de ligar uma carteira real.
Não se esqueça dos eventos duplicados. Alguns fornecedores voltam a enviar webhooks, e a mesma transferência pode aparecer mais do que uma vez no sistema se não tiver cuidado. O código que atualiza o pedido deve ser idempotente, ou seja, o mesmo evento não deve marcar o mesmo pedido como pago duas vezes. Esta simples proteção pode poupar horas de trabalho.
Lance, monitorize e melhore a experiência de checkout
A implementação na Vercel ou num serviço de alojamento semelhante costuma funcionar bem com Next.js, mas os pagamentos continuam a precisar de atenção. Confirme que o endpoint do webhook está acessível publicamente, que as variáveis de ambiente estão definidas em produção e que a compilação não depende de valores disponíveis apenas no ambiente local. Uma rota de pagamento que funciona no seu computador, mas falha em produção, é um erro clássico.
Os registos são importantes. Registe a criação de faturas, a receção de webhooks, os resultados das verificações e as alterações de estado. Inclua detalhes suficientes para acompanhar um pedido do início ao fim, mas não registe segredos. Se um cliente disser que pagou às 14:32, deve conseguir encontrar o evento correspondente em segundos, não em horas.
Pequenas alterações à experiência de utilização podem reduzir mais obstáculos do que se imagina. Mostre o montante duas vezes: uma no resumo do pedido e outra na etapa de pagamento. Mantenha o botão de pagamento visível depois de a fatura ser carregada. Acrescente um botão para copiar junto ao endereço. Explique claramente a etapa de confirmação, porque os utilizadores costumam atualizar a página enquanto esperam. Uma atualização do estado a cada 5 segundos pode parecer uma eternidade se a página não der qualquer indicação.
A partir daqui, o verdadeiro desafio não é o primeiro pagamento. É o segundo, o terceiro e aquele que falha na ligação entre uma carteira, uma rede e o seu backend Next.js. Se o sistema conseguir tratar bem destes 3 casos, terá um checkout em que os clientes podem confiar.
Comments