Checklist operacional para pagamentos cripto

Antes do lançamento

Faça uma vez e repita após qualquer alteração no servidor.

• A chave de API está só no servidor, numa variável de ambiente ou gestor de segredos, nunca no código do front-end nem num repositório.
• A URL de callback está guardada, é pública e usa HTTPS, e é acessível de fora da sua rede.
• O tratador do webhook responde exatamente HTTP 200, depressa, e é seguro executá-lo duas vezes. Qualquer outro estado, um tempo esgotado ou um redirecionamento contam como entrega falhada. Veja como proteger os webhooks de pagamentos cripto.
• Um pagamento de teste funciona de ponta a ponta. Pague um pequeno valor real, veja o webhook chegar e o pedido passar a pago. Ainda não há sandbox, por isso use pequenos valores reais.
• Uma nova tentativa funciona. Faça o endpoint falhar uma vez e confirme que a Qvard tenta de novo (cinco tentativas em cerca de seis minutos) sem cumprir o pedido em duplicado.
• Um saque funciona. Retire um pequeno valor para a sua carteira. Custa apenas a taxa de rede.
• As regras estão escritas: o que faz com um pagamento curto, como reembolsa e quem atende os clientes.

Todos os dias

Alguns minutos, de preferência à mesma hora.

• Pedidos por pagar fora da janela da taxa. A taxa na página de pagamento fica fixa por uma hora. Veja os pedidos que continuam à espera depois disso: foram abandonados ou perdeu-se uma notificação.
• Pagamentos curtos. Um pagamento com estado partial não envia webhook de conclusão. Verifique-os no painel, mantenha o pedido em espera e contacte o cliente. Veja como tratar pagamentos incompletos em USDT.
• Erros no endpoint do webhook. Uma série de pedidos falhados ou de respostas 401 indica um endpoint avariado ou uma chave que não corresponde. Configure um alerta em vez de descobrir no fim do dia.
• O total diário. Compare os pedidos que marcou como pagos com os pagamentos do painel. A API pública não tem rota para listar pagamentos, por isso é uma comparação com o seu próprio registo de webhooks. Veja a reconciliação de pagamentos para comerciantes cripto.

Todas as semanas

• Notificações perdidas. Se o painel mostra um pagamento concluído que o seu sistema de pedidos não mostra, reenvie a notificação a partir do painel e deixe o tratador idempotente aplicá-la.
• Padrões de suporte. Conte os pedidos sobre redes erradas, pagamentos curtos e «paguei e nada aconteceu». Se um se repete, corrija o texto no checkout ou na página do pedido, não cada ticket.
• Reembolsos. Verifique que cada reembolso enviado está registado no pedido original e foi para um endereço e rede que o cliente confirmou.
• Saldos por ativo e rede. Pagamentos em redes diferentes acumulam-se separadamente. Veja o que está onde antes de decidir o que levantar.
• Stock e expiração. Se reserva stock para pedidos por pagar, confirme que os pedidos expirados o libertam.

Todos os meses

• Reconcilie por completo. Cruze os pedidos do mês, o registo de webhooks e os pagamentos do painel e explique cada diferença. Registe a receita em dólares ao valor do pedido e a comissão e as taxas de saque como linhas separadas.
• Reveja os saques. Não há mensalidade; a comissão é individual para o seu projeto e, segundo a página de preços, começa em 1% e pode descer até 0,1%. Um saque custa apenas a taxa de rede, normalmente um valor fixo por transferência, por isso retire em montantes sensatos em vez de muitos pequenos. Veja as taxas de rede nas operações de pagamento cripto.
• Rode e audite os acessos. Verifique quem vê a chave de API e o painel e substitua a chave se saiu alguém que a tinha ou se suspeita de fuga.
• Releia o texto para clientes. O checkout ainda indica os ativos e redes aceites, a nota sobre taxas e a regra de reembolso? Continua verdadeiro?
• Consulte o seu contabilista. O tratamento fiscal e contabilístico dos recebimentos cripto depende do seu país; reveja a prática com regularidade.

Quando algo parece errado

Um guião curto para os casos comuns.

• Um cliente diz que pagou e o pedido consta por pagar. Veja o pagamento no painel. Se estiver concluído, reenvie a notificação. Se for partial, peça a diferença. Se não existir, peça os dados da transação e a rede usada.
• Rede errada. Os fundos não chegam como esperado e exigem tratamento manual. Mantenha um contacto de suporte visível no percurso de pagamento.
• Um pedido pago foi cumprido duas vezes. O tratador não é idempotente. Torne a atualização condicional («pago só se ainda não estiver pago») numa única instrução à base de dados.
• O webhook deixou de chegar. Teste o endpoint de fora da sua rede, veja o código de resposta no log de acesso e procure uma firewall, um redirecionamento ou um tratador lento. Veja a estratégia de novas tentativas de webhooks.
• Não tem certeza do que a API faz. A referência é a API de pagamentos cripto para programadores.

Guarde esta lista onde toda a equipa a veja e anote quem é responsável por cada linha.

FAQ