Desenvolvedores

Uma API de pagamentos previsível.

REST, valores em texto decimal com a moeda ao lado, Idempotency-Key em toda operação de dinheiro e webhooks assinados. Teste tudo no ambiente de teste antes de receber o primeiro PIX.

curl -X POST https://api.averopay.io/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: pedido-9821" \
  -H "Content-Type: application/json" \
  -d '{"amount":"150.00","currency":"BRL","description":"Plano Pro",
       "customer":{"name":"Ana Souza","document":{"type":"CPF","number":"529.982.247-25"},
       "email":"ana@exemplo.com"},"returnUrl":"https://loja.exemplo.com/obrigado"}'
Resposta
HTTP/1.1 201 Created
{
  "success": true,
  "message": "Cobrança criada com sucesso",
  "statusCode": 201,
  "data": {
    "id": "ch_7Hq2Kd8Wf91a",
    "object": "charge",
    "status": "PENDING",
    "amount": "150.00",
    "currency": "BRL",
    "fee": "2.25",
    "net": "147.75",
    "checkoutUrl": "https://checkout.averopay.io/c/Xr4pQ9mT2vLk8sWn3yHb6cJd1fGz5aKe7uRo0iNq4Ew"
  }
}
  • 9tentativas de entrega de cada webhook, em cerca de 3 dias
  • HMACSHA-256 com carimbo de tempo na assinatura de cada evento
  • "150.00"valores em texto decimal, sempre com a moeda ao lado
Chaves de API

Uma chave por ambiente, só o acesso que precisa.

Cada chave tem um nível por recurso: none, read ou write, e pode ter uma lista de IPs permitidos. Criar uma chave pede o código do app autenticador, ela aparece uma única vez e a AveroPay guarda só o hash.

  • 401API_KEY_INVALIDchave inválida, revogada ou vencida
  • 403API_KEY_SCOPEa chave não tem o escopo do recurso
  • 403IP_NOT_ALLOWEDo IP não está na lista da chave
sk_test_…Ambiente de testeNada movimenta dinheiro real. Simuladores de pagamento e eventos de webhook de verdade.
sk_live_…ProduçãoLiberada depois que o cadastro da empresa é aprovado.
Escopos por recurso
RecursoEscopoNíveis
Cobranças e links de pagamentochargesnone · read · write
Pagamentospayoutsnone · read · write
Saldo e extratobalancenone · read · write
Webhookswebhooksnone · read · write
Clientescustomersnone · read · write
Disputas (MED)disputesnone · read · write
POST /v1/charges
Idempotency-Key: pedido-9821        ← o mesmo pedido, a mesma chave

1ª vez               → 201 Created  (cria a cobrança)
de novo, mesmo corpo → 201 Created  (a resposta guardada)
                       Idempotent-Replayed: true
de novo, outro corpo → 409 IDEMPOTENCY_KEY_REUSED
depois de 7 dias     → conta como chave nova
Idempotency-Key

O mesmo pedido nunca vira duas cobranças.

O cabeçalho é obrigatório em toda operação de dinheiro: cobranças, devoluções e pagamentos. Se a rede cair e você repetir com o mesmo corpo, recebe a resposta guardada com Idempotent-Replayed: true. Se mudar o corpo com a mesma chave, a API recusa com 409 IDEMPOTENCY_KEY_REUSED.

A chave vale por 7 dias; depois disso conta como nova.

Webhooks

Eventos assinados, entregues com insistência.

Cada evento vem com X-Signature: t=<unix>,v1=<hex>, o HMAC-SHA256 de "<t>.<corpo cru>" com o segredo whsec_… do seu endpoint. Se o seu servidor não responder 2xx, a AveroPay tenta de novo, até 9 vezes em cerca de 3 dias.

Intervalos entre as tentativas1 min · 5 min · 30 min · 2 h · 6 h · 12 h · 24 h · 24 h
Cabeçalhos de cada entregaX-SignatureX-Event-IdX-Event-TypeX-Delivery-IdX-Delivery-Attempt
  • Confira a assinatura antes de tudo; recuse carimbos com mais de 300 s.
  • Use o X-Event-Id para tratar o mesmo evento duas vezes sem efeito duplicado.
  • Consulte a cobrança pela API quando precisar de certeza.
import { createHmac, timingSafeEqual } from 'node:crypto';

// Use o corpo cru, antes de qualquer JSON.parse: a assinatura é sobre os bytes recebidos.
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// Express: app.post('/webhooks/averopay', express.raw({ type: 'application/json' }), handler)
function handler(req, res) {
  const raw = req.body.toString('utf8');
  if (!verifySignature(raw, req.get('X-Signature') ?? '', process.env.AVEROPAY_WEBHOOK_SECRET)) return res.status(400).end();
  const event = JSON.parse(raw);
  // Trate cada X-Event-Id uma vez só: a mesma entrega pode chegar de novo.
  res.status(200).end();
}
Eventos

Tudo o que acontece, no seu endpoint.

  • charge.createdCobrança criada; o checkout já pode ser enviado.
  • charge.paidO pagador pagou. Tarifa e líquido já estão no extrato.
  • charge.underpaidem breveCripto: chegou menos que o valor.
  • charge.overpaidem breveCripto: chegou mais que o valor.
  • charge.late_paymentem breveCripto: pagamento depois do prazo.
  • charge.expiredO prazo acabou sem pagamento.
  • charge.canceledA cobrança foi cancelada antes do pagamento.
  • charge.failedA cobrança terminou sem pagamento por falha do provider ou do banco.
  • charge.refundedDevolvida por inteiro para quem pagou (devolução ou MED perdido).
  • charge.partially_refundedParte do valor voltou para quem pagou (devolução ou MED perdido).
  • payout.createdPagamento por PIX pedido (pode aguardar aprovação).
  • payout.approvedA aprovação liberou o pagamento; o status diz se segue para a análise da plataforma ou para o envio.
  • payout.paidO pagamento saiu e chegou ao destino.
  • payout.failedO pagamento não foi concluído: falhou, foi recusado ou cancelado (veja o status). O valor volta ao saldo.
  • payout.returnedO destino devolveu o valor; ele volta ao saldo.
  • refund.createdDevolução pedida.
  • refund.succeededA devolução chegou a quem pagou.
  • refund.failedA devolução não foi concluída; o valor volta ao saldo.
  • dispute.createdAbriu uma MED; a defesa pode ser montada no painel ou pela API.
  • dispute.updatedA MED mudou de etapa.
  • dispute.closedA MED foi encerrada, com o resultado.
  • payment_link.createdLink de pagamento criado.
  • payment_link.updatedO link mudou: nome, limite, validade ou status (pausado, reativado, arquivado).
  • test.pingEvento de teste enviado pelo painel para conferir o endpoint.

Cada endpoint escolhe os grupos que recebe: charge.*, payout.*, refund.* e dispute.*. O corpo de cada evento traz id, type, createdAt, environment e data.

Ambiente de teste

Teste o caminho inteiro antes de ir ao ar.

Chaves sk_test_, simuladores de pagamento e webhooks reais para o seu endpoint. Nada movimenta dinheiro.

  • Simular pagamentoNo checkout de uma cobrança de teste ou no painel: ela vira paga e dispara charge.paid.
  • Simular expiraçãoA cobrança vira expirada e dispara charge.expired.
  • Pagamento para uma chave PIXO pagamento de teste sai e dispara payout.paid.
  • Chave com "falha" no textoO pagamento falha, o valor volta ao saldo e dispara payout.failed.

Comece no ambiente de teste hoje.

Crie a conta, gere uma chave sk_test_ e faça a primeira cobrança. A produção libera depois da análise do cadastro.