Visão geral

A Avexus é infraestrutura de pagamentos: você cria cobranças Pix, recebe o dinheiro no seu saldo, acompanha o extrato, solicita saques e é avisado de cada mudança de estado por webhook.

Esta documentação cobre a API do lojista — a superfície pública, autenticada por chave de API. O painel e o checkout público do pagador têm as suas próprias telas, e aparecem aqui só quando são o caminho para alguma coisa (gerar chaves, autorizar um parceiro de split, acompanhar um saque).

Ambientes

A Avexus tem dois ambientes, com URLs, bancos e credenciais distintos:

Produção (live)

https://api.avexus.app

Sandbox (demo)

https://sandbox-api.avexus.app

O sandbox replica o fluxo Pix inteiro — cobrança, confirmação, saque, disputa e webhook — sem mover dinheiro de verdade. As chaves de um ambiente não funcionam no outro. Veja o guia do sandbox para os valores que simulam cada status.

TODO(contrato)

Os hostnames acima seguem a convenção do domínio avexus.app, mas ainda dependem da confirmação da frente F0 — Contrato (mapa de rotas e publicação). Se o API-CONTRACT.md fixar outros hosts, esta página e todos os exemplos curl precisam ser atualizados junto.

Autenticação em uma linha

Toda chamada leva o par de chaves nos headers x-api-key (pk_…) e x-token (sk_…). Todo POST leva também um idempotency-key.

Requisição autenticada

curl --request GET \
  --url https://api.avexus.app/api/balance \
  --header 'x-api-key: pk_1a2b3c4d5e6f' \
  --header 'x-token: sk_9f8e7d6c5b4a3f2e1d0c9b8a' \
  --header 'x-timezone: America/Sao_Paulo'

Os detalhes — como gerar o par, rotacionar, escopos, limites de requisição e idempotência — estão em Autenticação.

Envelope de resposta

Toda resposta de sucesso usa o mesmo envelope, com code, content, message e timestamp:

Sucesso

{
  "code": 200,
  "content": {
    "currency": "BRL",
    "balance": 1250.75,
    "blocked": 120.0,
    "reserve": 80.0,
    "processing": 45.5
  },
  "message": "Balance returned",
  "timestamp": "2026-07-24T18:38:27.310Z"
}

Erros usam uma forma própria, mais curta:

Erro (400)

{
  "error": 400,
  "message": "Invalid request payload"
}

A lista completa está em Códigos de erro.

Reais na API, centavos por dentro

Os campos de dinheiro trafegam em reais (4.00, 250.5), mas o cálculo interno é inteiro em centavos — não existe fração de centavo em taxa, split ou comissão.

O que dá para fazer

Cobranças

POST /api/transactions cria uma cobrança Pix e devolve o copia-e-cola; GET /api/transactions consulta por magic_id, status, external_ref ou end_to_end.

Checkout

Página de pagamento hospedada pela Avexus: você cria a cobrança, o pagador conclui numa URL nossa e você recebe o webhook.

Links de pagamento

Link reutilizável (avexus.app/pay/<slug>) para vender sem escrever integração nenhuma.

Saldo e extrato

GET /api/balance com os recortes balance, blocked, reserve e processing, mais exportação em CSV de cobranças e saques.

Saques

POST /api/withdrawals envia dinheiro para uma chave Pix; GET /api/withdrawals acompanha o status.

Webhooks

Registre endpoints e receba transaction, withdraw e dispute assinados com HMAC SHA256.

Por onde começar

QuickstartPrimeira cobrança Pix de ponta a ponta, do curl ao webhook.

AutenticaçãoChaves, escopos, idempotência e limites de requisição.

Receber webhooksPayloads, headers e verificação da assinatura HMAC.

Ambiente sandboxSimule cada status de transação com valores determinísticos.

Boas práticas

• Guarde o magic_id da Avexus e envie o seu external_ref: a conciliação fica possível pelos dois lados.
• Gere um idempotency-key único por operação. Em caso de timeout, repita a requisição com a mesma chave.
• Valide o header x-webhook-signature antes de processar qualquer webhook.
• Mantenha os handlers de webhook idempotentes — a mesma entrega pode chegar mais de uma vez.
• Nunca embuta o x-token (sk_…) em código que roda no navegador ou no app do cliente.