Integrar uma API de pagamento cripto segue um formato previsível, independentemente do provedor: você cria uma fatura, redireciona ou incorpora um checkout, recebe webhooks assíncronos conforme o pagamento avança, verifica-os e reconcilia com seus próprios registros. A parte difícil não é o caminho feliz — são as bordas.
O fluxo central
A maioria dos gateways expõe uma API REST com o mesmo ciclo de vida. Você a chama no lado do servidor (nunca exponha uma chave de API no navegador) e trata o webhook — não o redirecionamento do navegador — como a fonte da verdade sobre se um pedido está pago.
Projete primeiro a máquina de estados do seu pedido: pendente → pago a menor/pago → confirmado → concluído, com ramos explícitos para expirado e pago a maior. Montar isso de antemão evita os condicionais emaranhados que causam duplo faturamento.
- Crie uma fatura com valor, moeda, ID do pedido e uma URL de webhook.
- Mostre o checkout hospedado ou renderize o endereço e o valor você mesmo.
- Receba webhooks a cada mudança de estado e verifique sua assinatura.
- Confirme que o pagamento atingiu as confirmações exigidas antes de atender.
- Reconcilie o webhook com a transação on-chain e com seu pedido.
Criando uma fatura
Uma fatura vincula um valor específico a um pedido específico por um tempo limitado. Envie o ID do seu pedido como metadado para que o webhook possa ser correspondido de volta sem adivinhação, e armazene o ID da fatura que o gateway retorna.
As cotações expiram — o gateway trava uma taxa por alguns minutos. Persista a expiração e o status da fatura para que sua UI possa exibir um cronômetro e para que um pagamento atrasado seja tratado como caso de reconciliação, não como pedido perdido.
Os webhooks são a fonte da verdade
O redirecionamento do navegador após o pagamento é uma conveniência, não uma garantia — o usuário pode fechar a aba. O webhook que seu servidor recebe é o que você trata. Verifique cada webhook: cheque a assinatura (geralmente um HMAC sobre o corpo bruto com seu segredo) antes de confiar em qualquer campo.
Torne o tratamento de webhook idempotente. Os gateways reenviam entregas, então o mesmo evento 'pago' pode chegar duas vezes; baseie seu processamento no ID do evento ou da fatura e faça entregas repetidas serem no-op. Retorne um 2xx rapidamente e faça o trabalho lento de forma assíncrona para que o gateway não expire e reenvie sem necessidade.
Confirmações e finalidade
Um pagamento pode ser visto (na mempool ou com zero confirmações) muito antes de ser definitivo. Defina um limite de confirmações apropriado ao valor e à rede, e só atenda quando for atingido. Para pequenos pagamentos de stablecoin em redes rápidas isso é veloz; para valores grandes, aguarde mais.
Proteja-se contra reorganizações e gastos duplos confiando no estado 'confirmado' do gateway em vez de sua própria primeira observação, e não liberando mercadorias em um pagamento com zero confirmações a menos que você aceite o risco.
Reconciliação e os modos de falha
A reconciliação é o trabalho diário de provar que cada pedido 'pago' corresponde a uma transação on-chain real e vice-versa. Armazene o hash da transação, o valor recebido e a rede em cada pedido para que uma discrepância seja uma consulta, não uma investigação.
Planeje explicitamente para pagamentos a menor (o comprador enviou pouco), pagamentos a maior (reembolse a diferença ou credite), envios na rede errada e faturas expiradas-e-depois-pagas. Esses não são casos de borda raros em escala — são eventos semanais, e um sistema que os trata silenciosamente é o que 'pronto para produção' realmente significa.
Perguntas frequentes
Devo confiar no redirecionamento do navegador ou no webhook?
No webhook. O redirecionamento pode se perder se o usuário fechar a aba, e pode ser forjado. Verifique a assinatura do webhook no lado do servidor e trate-o como o sinal oficial de que um pedido está pago.
Como impeço que um webhook seja processado duas vezes?
Torne o tratamento idempotente. Os gateways reenviam entregas, então baseie sua lógica no ID da fatura ou do evento e faça uma repetição ser no-op. Nunca atenda um pedido duas vezes porque o mesmo evento 'pago' chegou de novo.
Quantas confirmações devo aguardar?
Depende do valor e da rede. Pequenos pagamentos de stablecoin em redes rápidas podem ser tratados como definitivos quase imediatamente; valores maiores justificam mais confirmações. Use o estado 'confirmado' do gateway em vez de sua própria primeira observação.
O que acontece se um cliente pagar a menor ou a maior?
Trate ambos explicitamente. Os gateways sinalizam pagamentos a menor para que você possa solicitar a diferença ou reembolsar; para pagamentos a maior, você reembolsa o excesso ou o credita. Construir esses ramos de antemão é a diferença entre uma demo e produção.