API de gateway de pagamento cripto: 12 pontos para checar antes de integrar
Toda API de pagamento cripto cria uma cobrança. As diferenças aparecem nos reenvios, nos pagamentos parciais e nos webhooks que falham. Um checklist de 12 pontos para desenvolvedores, com a forma como a API do mistKET trata cada um.
Toda API de gateway de pagamento cripto promete a mesma coisa: criar uma cobrança, receber o pagamento, receber um callback. As diferenças só aparecem depois — quando duas requisições disputam o mesmo pedido, quando o cliente envia um pouco menos que o valor da cobrança, quando seu servidor fica uma hora fora do ar ou quando um atacante repete uma requisição interceptada. Escolher a API com cuidado economiza muito mais tempo do que integrá-la às pressas.
Este é um checklist para desenvolvedores e CTOs que comparam APIs de pagamento cripto antes de escrever qualquer código. Para cada ponto, você vê o que procurar, por que isso importa e como a API do mistKET resolve. Se já escolheu e quer o código passo a passo, vá direto para o nosso guia de integração de API de pagamento cripto.
O conjunto mínimo de endpoints
Uma API de pagamento cripto utilizável precisa de mais do que “criar pagamento”. No mínimo, procure:
| Recurso | Por que você precisa | Endpoint do mistKET |
|---|---|---|
| Criar cobrança | Uma solicitação de pagamento por pedido, com validade | POST /invoices |
| Consultar cobrança | Conciliar quando um webhook se perde | GET /invoices/{uuid} |
| Listar e filtrar cobranças | Telas de back-office e conciliação noturna | GET /invoices |
| Cancelar cobrança | Liberar estoque quando um pedido é abandonado | POST /invoices/{uuid}/cancel |
| Ativos suportados | Mostrar apenas as redes que podem ser pagas agora | GET /assets |
| Cotação | Exibir o valor em cripto antes de criar a cobrança | GET /rate |
| Health check | Monitoramento e fallbacks controlados | GET /health |
Se o provedor não permite consultar nem listar cobranças, você é obrigado a confiar cegamente nos webhooks — uma posição ruim na primeira vez que uma entrega falhar.
1. Autenticação: toda requisição é assinada?
Uma API key enviada num cabeçalho é a opção mais fraca: quem interceptar ou vazar essa chave pode criar e cancelar cobranças. Prefira uma API em que cada requisição é assinada com um segredo que nunca trafega pela rede. As requisições ao mistKET levam X-Api-Key, X-Api-Timestamp e uma assinatura HMAC-SHA256 do timestamp e do corpo bruto. A secret é exibida uma única vez no painel do lojista.
2. Proteção contra replay
A assinatura sozinha não impede que alguém reenvie uma requisição interceptada. Procure uma janela de timestamp e suporte a nonce. O mistKET rejeita timestamps com diferença maior que ±300 segundos em relação ao horário do servidor e recusa a mesma assinatura duas vezes em requisições que alteram estado. A versão 2 da assinatura acrescenta um nonce por requisição e assina também o método e o caminho, de modo que uma assinatura não pode ser reaproveitada em outro endpoint.
3. Idempotência na criação de cobranças
Conexões dão timeout. Se o seu checkout repetir uma chamada de “criar cobrança”, você não pode acabar com duas cobranças para um pedido. Uma boa API oferece uma chave de idempotência. No mistKET, o seu próprio order_id cumpre esse papel: chamar de novo com o mesmo ID de pedido devolve a cobrança existente com "idempotent": true em vez de criar uma nova.
4. Um modelo de status que cobre pagamentos reais
“Pago / não pago” não basta. Clientes enviam um pouco menos porque a corretora descontou uma taxa, ou enviam a mais, ou pagam depois do vencimento. Confira se a API expõe esses casos de forma explícita. As cobranças do mistKET passam por new, pending, underpaid, paid, confirmed, overpaid, expired e cancelled, com campos como paid_amount, remaining_amount, can_pay_remaining e under_review, para que o seu código nunca precise adivinhar.
paid significa que a transferência foi detectada e aguarda confirmações; só entregue pedidos em confirmed ou overpaid.5. Confirmações visíveis
A API deve informar quantas confirmações de bloco um pagamento tem e quantas são exigidas, além do hash da transação e de um link para o explorador. Isso transforma chamados de suporte sobre pagamentos em consultas rápidas. O mistKET retorna confirmations, required_confirmations e um array transactions[] com hash, valor, status e URL do explorador para cada cobrança.
6. Trava de cotação e moedas de preço
Você define o preço em moeda fiduciária; o cliente paga em cripto. Pergunte quais moedas fiduciárias são aceitas e por quanto tempo a cotação fica garantida. O mistKET aceita preços em USD, EUR, TRY, RUB, GBP e AED (ou diretamente no símbolo da cripto), trava a cotação durante toda a validade da cobrança e permite definir essa validade entre 5 e 1.440 minutos por cobrança.
7. Seleção de rede
Dá para fixar a rede na chamada da API ou deixar o cliente escolher na página hospedada? As duas opções são úteis: fixar serve para bots e fluxos automatizados; deixar o cliente escolher reduz pagamentos na rede errada. O mistKET suporta as duas via pay_currency + network ou asset_id, e GET /assets informa available: false quando uma rede não tem endereço livre. Hoje está habilitado o USDT na TRON (TRC-20); outros ativos e redes são habilitados por lojista, sob pedido. Veja USDT TRC20 vs ERC20 para entender por que a TRON é o padrão mais comum.
8. Webhooks assinados, com reenvio e rastreáveis
É nos webhooks que a maioria das integrações quebra. Verifique quatro coisas: o payload é assinado, há um timestamp para rejeitar entregas antigas, entregas com falha são reenviadas por horas (não segundos) e cada entrega tem um ID que você pode usar para deduplicação. O mistKET assina os webhooks com uma webhook secret separada, envia os cabeçalhos X-Mistket-Delivery e X-Mistket-Event e reenvia respostas não-2xx após 10 s, 30 s, 2 min, 10 min, 30 min, 1 h, 2 h e 3 h, com o histórico de entregas visível no painel. Nosso artigo sobre webhooks de pagamento cripto aprofunda o design do handler.
9. Erros e limites de requisição documentados
Você deve saber de antemão como é uma assinatura inválida, um IP bloqueado ou um erro de validação. O mistKET retorna um corpo consistente { "success": false, "error": … } com detalhes por campo nos erros de validação, usa códigos padrão (401, 403, 404, 422, 429, 503) e documenta seu limite: 120 requisições por minuto por API key.
10. Controles no nível de rede
Uma lista de IPs permitidos faz com que uma chave vazada não sirva para nada fora dos seus servidores. O mistKET permite configurá-la no painel; requisições de outros endereços recebem 403. Somado às requisições assinadas e às janelas curtas de timestamp, isso fecha os caminhos de ataque mais comuns.
11. Sem dependência de SDK
SDKs são práticos até ficarem para trás em relação à versão da sua linguagem. Uma API baseada em HTTPS e JSON simples, em que assinar é uma única chamada HMAC, funciona em PHP, Node.js, Python, Go ou num script shell. O mistKET publica clientes prontos para copiar e colar em PHP, Node.js e Python na sua documentação da API, mas nenhum deles é obrigatório.
12. Um caminho manual para quem não programa
Mesmo empresas API-first precisam cobrar um cliente avulso de vez em quando. Verifique se as cobranças também podem ser criadas num painel e compartilhadas como link, para que vendas e suporte não precisem acionar os desenvolvedores. No mistKET, as mesmas cobranças ficam disponíveis no painel do lojista, e toda página de checkout hospedado funciona como link de pagamento.
GET /invoices/{uuid} e compare. Isso valida a assinatura, o handler de webhook e a conciliação de uma só vez.Sinais de alerta ao avaliar uma API de pagamento cripto
- Webhooks sem assinatura ou “protegidos” apenas por uma URL secreta.
- Nenhuma forma de consultar uma cobrança depois de criada.
- Nenhum status de pagamento a menor ou a maior — os casos especiais vão parar no chat de suporte.
- Reenvios por apenas alguns minutos, ou nenhum log de entregas.
- Limites de requisição e formatos de erro sem documentação.
- Preço pouco claro por transação — compare com o nosso guia de taxas de gateway de pagamento cripto.
Como obter acesso à API do mistKET
Os lojistas são aprovados pela equipe do mistKET: mande uma mensagem para @mistnetwork no Telegram com o seu site, o tipo de negócio e o volume esperado. Depois da aprovação, você cria sua API key, sua secret e as configurações de webhook no painel do lojista. Uma integração típica leva uma tarde.
Veja a seção para desenvolvedores, os preços e a referência completa da API antes de começar.
