Entendendo Gateways e APIs
Domine a arquitetura por trás dos pagamentos crypto: como funcionam os gateways, APIs, webhooks e todo o fluxo técnico de uma transação.
💡 Por que isso é importante
Escolher o gateway errado pode custar 40% a mais em taxas e causar problemas de integração que levam meses para resolver. Entender a arquitetura técnica garante que você tome decisões informadas e implemente soluções robustas desde o início.
O Que São Gateways de Pagamento Crypto
🏦 Definição Técnica
Um gateway de pagamento crypto é um serviço intermediário que simplifica a integração entre sua aplicação e as redes blockchain, oferecendo APIs padronizadas para processar transações em múltiplas criptomoedas.
✅ O que o Gateway Faz
- • Gera endereços únicos para cada pagamento
- • Monitora transações na blockchain
- • Converte entre diferentes criptomoedas
- • Envia confirmações via webhook
- • Calcula taxas de rede automaticamente
- • Fornece histórico de transações
❌ O que Você Não Precisa Fazer
- • Monitorar blockchains manualmente
- • Gerenciar carteiras privadas
- • Implementar lógica de confirmação
- • Calcular taxas de transação
- • Lidar com diferentes protocolos
- • Sincronizar dados de múltiplas redes
Arquitetura de um Gateway Crypto
🏗️ Componentes Principais
Camada de API
Interface padronizada para criar pagamentos, consultar status e gerenciar transações.
Monitor de Blockchain
Sistema que monitora múltiplas redes blockchain em tempo real para detectar pagamentos.
Gerenciador de Carteiras
Gera endereços únicos e gerencia chaves privadas de forma segura para cada transação.
Sistema de Notificações
Envia webhooks para sua aplicação quando o status de um pagamento muda.
Fluxo Completo de uma Transação
Criação do Pagamento
Sua Aplicação →
- • Usuário clica em "Pagar com Crypto"
- • App faz POST para /api/crypto/create
- • Envia amount, currency, order_id
← Gateway Responde
- • Gera endereço único Bitcoin/Ethereum
- • Calcula taxa de conversão atual
- • Retorna payment_id e QR code
Pagamento Realizado
Usuário →
- • Escaneia QR code com carteira
- • Confirma transação na blockchain
- • Aguarda confirmações de rede
← Gateway Monitora
- • Detecta transação na mempool
- • Status muda para "confirming"
- • Conta confirmações de bloco
Confirmação e Webhook
Gateway →
- • Transação atinge confirmações necessárias
- • Status final: "completed" ou "failed"
- • Envia webhook para sua URL
← Sua Aplicação
- • Recebe POST em /webhook/crypto
- • Valida assinatura do webhook
- • Atualiza status do pedido
Comparação dos Principais Gateways
| Gateway | Taxas | Criptomoedas | Conversão | KYC |
|---|---|---|---|---|
Cryptomus ⭐ Recomendado | 0.4% - 1.5% | 30+ moedas | Auto-conversão | Básico |
CoinGate Europeu | 1% - 2% | 70+ moedas | Sim | Rigoroso |
BitPay Tradicional | 1% - 2.5% | 15 moedas | Sim | Muito rigoroso |
NOWPayments Altcoins | 0.5% - 1% | 400+ moedas | Opcional | Mínimo |
🎯 Por que Cryptomus é Nossa Escolha
Baixas taxas: Começam em 0.4% para volume alto
Setup rápido: KYC básico, aprovação em 24h
Auto-conversão: Receba em USD/EUR automaticamente
API moderna: Documentação clara e SDKs
Webhooks confiáveis: Retry automático
Suporte 24/7: Chat e Telegram responsivos
Anatomia de uma API Request
🔧 Criando um Pagamento (Exemplo Cryptomus)
// POST https://api.cryptomus.com/v1/payment
{
"amount": "99.99", // Valor em USD
"currency": "USD", // Moeda de origem
"order_id": "order_123", // ID único do seu sistema
"url_return": "https://seu-site.com/success",
"url_callback": "https://seu-site.com/webhook",
"is_payment_multiple": false, // Um pagamento por endereço
"lifetime": 7200, // 2 horas para expirar
"to_currency": "USDT" // Criptomoeda que aceita
}
// Resposta da API
{
"state": 0, // 0 = sucesso
"result": {
"uuid": "abc123-def456", // ID único do gateway
"order_id": "order_123", // Seu ID original
"amount": "99.99",
"currency": "USD",
"payer_amount": "100.15", // Valor incluindo taxas
"payer_currency": "USDT",
"address": "TQn9Y2...7Kc", // Endereço para pagamento
"from": ["USDT"], // Moedas aceitas
"network": "tron", // Rede blockchain
"url": "https://pay.cryptomus.com/pay/abc123",
"expired_at": 1640995200 // Unix timestamp
}
}✅ Campos Obrigatórios
- amount: Valor do pagamento
- currency: Moeda de precificação
- order_id: ID único (não repetir)
- url_callback: URL para webhooks
💡 Campos Opcionais
- lifetime: Tempo limite (padrão 24h)
- to_currency: Cripto específica
- url_return: Redirect pós-pagamento
- additional_data: Metadados extras
Webhooks: O Coração do Sistema
🔔 Por que Webhooks São Críticos
Diferente de APIs tradicionais, pagamentos crypto são assíncronos. Uma transação pode levar de segundos a horas para ser confirmada. Webhooks garantem que sua aplicação seja notificada imediatamente quando o status muda.
❌ Sem Webhooks
- • Fazer polling constante na API
- • Usuário não sabe quando pagamento confirma
- • Atraso para liberar produto/serviço
- • Consumo desnecessário de API
✅ Com Webhooks
- • Notificação instantânea de mudanças
- • UX responsiva e em tempo real
- • Automação completa de processos
- • Zero desperdício de recursos
📨 Exemplo de Webhook Payload
// POST para sua URL de callback
{
"type": "payment", // Tipo de evento
"uuid": "abc123-def456", // ID do pagamento
"order_id": "order_123", // Seu ID original
"amount": "99.99",
"currency": "USD",
"payer_amount": "100.15",
"payer_currency": "USDT",
"status": "paid", // Status atual
"is_final": true, // Status é definitivo?
"network": "tron",
"txid": "a1b2c3d4...", // Hash da transação
"block_number": 45123456, // Bloco confirmado
"confirmations": 12, // Número de confirmações
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:45:00Z",
"sign": "sha256_signature" // Assinatura de segurança
}🛡️ Segurança Crítica
SEMPRE valide a assinatura do webhook. Qualquer pessoa pode fazer POST para sua URL, mas apenas o gateway conhece a chave secreta para gerar a assinatura correta.
Estados de Pagamento e Transições
wait_payment
Pagamento criado, aguardando transação do usuário. QR Code ativo.
confirming
Transação detectada na mempool, aguardando confirmações de rede (1-6 blocos).
paid
Pagamento confirmado com sucesso. Pode liberar produto/serviço.
fail / expired
Pagamento expirou ou falhou. Valor insuficiente, rede congestionada, etc.
💡 Dicas de UX
wait_payment: Mostrar QR code e instruções
confirming: "Pagamento recebido, confirmando..."
paid: "Sucesso! Produto liberado"
fail/expired: "Expirou, gerar novo pagamento?"
🎯 Exercício Prático
Mapeamento de Arquitetura
Tarefa 1: Desenhe o Fluxo
Crie um diagrama (pode ser no papel) mostrando:
- 1. Usuário fazendo pedido na sua app
- 2. Sua API comunicando com gateway
- 3. Gateway gerando endereço crypto
- 4. Usuário enviando transação
- 5. Gateway monitorando blockchain
- 6. Webhook sendo enviado para você
- 7. Sua app liberando o produto
Tarefa 2: Cenários de Erro
Para cada cenário, defina como sua aplicação deve reagir:
• Gateway está fora do ar
• Webhook não chegou em 1 hora
• Usuário pagou valor errado
• Transação falhou por taxa baixa
• Pagamento parcialmente confirmado
• Rede blockchain congestionada
Tarefa 3: Escolha do Gateway
Baseado no seu projeto, responda:
- • Qual volume mensal de transações você espera?
- • Precisa receber em cripto ou converter para fiat?
- • Seu público está em quais países?
- • Pode passar por processo KYC rigoroso?
- • Quais criptomoedas são prioridade?
💡 Dica: Não há resposta "correta" para essas tarefas. O objetivo é você pensar criticamente sobre cada decisão arquitetural antes de começar a implementar.
🎯 Resumo da Aula
Gateways crypto abstraem a complexidade das blockchains fornecendo APIs simples, monitoramento automático e webhooks confiáveis. A escolha do gateway correto e o entendimento da arquitetura são fundamentais para uma implementação robusta. Na próxima aula, vamos analisar os custos e ROI em detalhes.