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"}'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
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.
- 401
API_KEY_INVALIDchave inválida, revogada ou vencida - 403
API_KEY_SCOPEa chave não tem o escopo do recurso - 403
IP_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.| Recurso | Escopo | Níveis |
|---|---|---|
| Cobranças e links de pagamento | charges | none · read · write |
| Pagamentos | payouts | none · read · write |
| Saldo e extrato | balance | none · read · write |
| Webhooks | webhooks | none · read · write |
| Clientes | customers | none · read · write |
| Disputas (MED) | disputes | none · 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 novaO 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.
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.
X-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();
}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.
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.