Como Integrar uma API de Pagamentos Cripto no Seu Produto

Integrar uma API de pagamentos cripto não precisa ser complicado. O fluxo essencial é sempre o mesmo: você autentica com uma chave de API, cria uma cobrança, recebe um endereço de depósito e escuta webhooks para saber quando o pagamento foi confirmado. Este guia mostra o caminho feliz e os detalhes que separam uma integração frágil de uma robusta.

1. Autenticação com chave de API

Toda requisição autenticada envia sua chave secreta no header Authorization. Nunca exponha a chave secreta no front-end, ela vive apenas no seu servidor.

curl https://api.aeses.io/v1/charges \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

2. Criando uma cobrança

Uma cobrança (charge) representa um valor a receber. Você define o valor, a moeda e a rede aceita, e recebe de volta um endereço de depósito efêmero com tempo de expiração.

{
  "amount": "150.00",
  "currency": "USDT",
  "network": "polygon",
  "reference": "pedido_8842",
  "metadata": { "customer_id": "cus_123" }
}

3. Recebendo confirmações via webhook

Em vez de ficar consultando a API em loop, configure um endpoint de webhook. A plataforma envia um POST assinado quando o status muda, por exemplo, de pending para confirmed.

import { createHmac, timingSafeEqual } from 'crypto'

function verifyWebhook(rawBody: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signature)
  return a.length === b.length && timingSafeEqual(a, b)
}

4. Idempotência: o detalhe que evita dor de cabeça

Webhooks podem ser entregues mais de uma vez. Sua lógica de processamento precisa ser idempotente: processar o mesmo evento duas vezes não pode creditar o pedido duas vezes. A forma mais simples é registrar o ID do evento já processado antes de aplicar o efeito.

• Guarde o event.id em uma tabela com índice único.
• Ao receber um webhook, tente inserir o ID; se já existir, retorne 200 sem reprocessar.
• Só então aplique o efeito de negócio (liberar o pedido, dar baixa, etc.).
• Responda 2xx rapidamente: o processamento pesado vai para uma fila.

5. Indo para produção

1. Troque as chaves de teste (sk_test_) pelas de produção (sk_live_).
2. Configure o endpoint de webhook de produção e valide a assinatura.
3. Implemente retry com backoff no seu lado para chamadas que falharem.
4. Monitore os eventos no painel e registre logs com o request id de cada chamada.