AULA 02

18 min

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

API

Camada de API

Interface padronizada para criar pagamentos, consultar status e gerenciar transações.

Endpoints: /payment/create, /payment/status, /webhook/callback

⛓️

Monitor de Blockchain

Sistema que monitora múltiplas redes blockchain em tempo real para detectar pagamentos.

Bitcoin, Ethereum, Tron, Binance Smart Chain, Polygon, etc.

💎

Gerenciador de Carteiras

Gera endereços únicos e gerencia chaves privadas de forma segura para cada transação.

HD Wallets, Multi-sig, Hot/Cold Storage

🔔

Sistema de Notificações

Envia webhooks para sua aplicação quando o status de um pagamento muda.

Pending → Confirming → Completed → Failed

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)

create-payment.json

✅ 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

webhook-payload.json

🛡️ 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

wait_payment

Pagamento criado, aguardando transação do usuário. QR Code ativo.

CONF

confirming

Transação detectada na mempool, aguardando confirmações de rede (1-6 blocos).

PAID

paid

Pagamento confirmado com sucesso. Pode liberar produto/serviço.

FAIL

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.

🚀Próxima Aula