Visão geral

A API REST da AveroPay recebe e paga por PIX: cobranças com checkout hospedado, links de pagamento, pagamentos para chaves PIX, devoluções e a defesa de MED. JSON nos dois sentidos, valores em texto decimal com a moeda ao lado e um webhook assinado para cada mudança.

Endereço e autenticação

Todas as rotas ficam em https://api.averopay.io/v1 (o endereço dos exemplos). Cada chamada leva a sua chave em Authorization: Bearer sk_…; o prefixo da chave decide o ambiente: sk_test_ no teste, sk_live_ em produção. Tudo o que a API devolve é da empresa e do ambiente da chave: uma chave de teste nunca vê dado de produção.

GET /v1/account não exige escopo e responde com a empresa, o ambiente e os escopos da chave: é o jeito mais rápido de conferir a integração. Mais em Chaves de API e escopos.

Convenções

  • Valores em texto decimal com ponto, na escala da moeda ("150.00" em BRL), sempre com currency ao lado. Moedas nunca são somadas nem convertidas.
  • Datas em ISO 8601, em UTC na resposta ("2026-11-03T14:32:08.512Z").
  • Ids com prefixo: ch_ cobrança, plk_ link de pagamento, po_ pagamento, re_ devolução, dsp_ disputa, evt_ evento. Guarde como texto, sem supor tamanho nem formato.
  • Campo desconhecido no corpo é recusado com VALIDATION_ERROR. Já nas respostas e nos webhooks, campos novos podem aparecer: ignore o que o seu código não conhece.
  • Criar cobrança, devolução, pagamento, link de pagamento e evidência de MED exige Idempotency-Key.

Envelope de resposta

Toda resposta vem no mesmo envelope: success, message (em português, para pessoas), statusCode (igual ao status HTTP) e data. No erro, data dá lugar a error.code, em inglês e estável, e error.details quando houver. Veja Formato de erro.

{
  "success": true,
  "message": "Cobrança",
  "statusCode": 200,
  "data": { "id": "ch_7Hq2Kd8Wf91a", "object": "charge", … }
}

Paginação

As listas (GET /v1/charges, /v1/payment-links, /v1/payouts, /v1/disputes, /v1/beneficiaries e /v1/events) vêm da mais recente para a mais antiga, em data.items, com data.nextCursor. Para a próxima página, mande ?cursor= com esse valor; null é o fim. limit vai de 1 a 100 (padrão 20). O cursor é opaco: não monte nem altere.

As listas de uma cobrança (/refunds e /disputes) e as contas de saque vêm inteiras, sem cursor. /v1/customers pagina por número (?page=, 20 por página, com total): a ordem muda a cada pagamento. Exemplo completo em Listar cobranças.

Limite de requisições

Cada chave faz até 1.200 requisições por minuto. Passou disso, a resposta é 429 RATE_LIMITED, com os segundos até a janela abrir de novo em error.details.retryAfterSeconds.

Limite atingido
HTTP/1.1 429 Too Many Requests
{
  "success": false,
  "message": "Muitas requisições. Tente novamente em instantes",
  "statusCode": 429,
  "error": { "code": "RATE_LIMITED", "details": { "retryAfterSeconds": 23 } }
}

X-Request-Id

Toda resposta traz X-Request-Id. Se você mandar o seu (de 8 a 64 caracteres: letras, números, _ e -), ele volta igual; senão vem um req_…. Guarde nos seus logs e mande junto quando falar com o suporte. As chamadas a /v1 também aparecem no painel, em Desenvolvedores › Logs de requisições.

Rotas

Rotas da API
MétodoRotaEscopoO que faz
GET/v1/accountnenhumEmpresa, ambiente e escopos da chave usada.
GET/v1/balancesbalance: readSaldos por moeda: disponível, a receber, reserva e bloqueado.
POST/v1/chargescharges: writeCriar cobrança
GET/v1/chargescharges: readListar cobranças
GET/v1/charges/:idcharges: readConsultar cobrança
POST/v1/charges/:id/cancelcharges: writeCancelar uma cobrança pendente
POST/v1/charges/:id/refundscharges: writeCriar devolução
GET/v1/charges/:id/refundscharges: readDevoluções da cobrança.
GET/v1/refunds/:idcharges: readUma devolução.
GET/v1/charges/:id/disputesdisputes: readDisputas (MED) da cobrança.
POST/v1/payment-linkscharges: writeCriar link de pagamento
GET/v1/payment-linkscharges: readLinks de pagamento
GET/v1/payment-links/:idcharges: readUm link, com usos e recebido.
PATCH/v1/payment-links/:idcharges: writeNome, limite de usos e validade.
POST/v1/payment-links/:id/pause · activate · archivecharges: writePausar, reativar ou arquivar.
POST/v1/payoutspayouts: writeCriar pagamento PIX
GET/v1/payoutspayouts: readPagamentos, mais recentes primeiro.
GET/v1/payouts/:idpayouts: readUm pagamento.
POST/v1/payouts/:id/cancelpayouts: writeCancela um pagamento ainda não enviado.
POST/v1/beneficiariespayouts: writeSalva um destino de terceiro.
GET/v1/beneficiariespayouts: readBeneficiários (filtro rail).
GET/v1/beneficiaries/:idpayouts: readUm beneficiário.
POST/v1/beneficiaries/:id/archivepayouts: writeArquiva um beneficiário.
GET/v1/settlement-accountspayouts: readContas de saque da empresa (cadastro só no painel).
GET/v1/disputesdisputes: readComo funciona a MED
GET/v1/disputes/:iddisputes: readUma disputa, com o que a empresa já enviou.
POST/v1/disputes/:id/evidencedisputes: writeEnviar defesa
POST/v1/disputes/:id/defensedisputes: writeDefesa estruturada.
PATCH/v1/disputes/:id/commentdisputes: writeExplicação da empresa.
GET/v1/customerscustomers: readClientes (os pagadores das cobranças), quem pagou por último primeiro; busca por ?q= e página por ?page=.
GET/v1/customers/:idcustomers: readUm cliente, com o pago por moeda e as cobranças mais recentes.
GET/v1/eventswebhooks: readEventos já emitidos
GET/v1/events/:idwebhooks: readUm evento pelo X-Event-Id.
GET/v1/banks?method=PSEcharges: readBancos do PSE (Colômbia): o código vai em customer.bankCode da cobrança.

O que ainda não existe

  • SDK oficial: ainda não existe. Use HTTP direto; os exemplos usam fetch (Node.js) e requests (Python).
  • Chaves de API e endpoints de webhook: só pelo painel, com o código do app autenticador. Não há rota para isso na API.
  • Aprovar ou recusar pagamentos: só no painel (a aprovação vira o evento payout.approved).

Hoje a API recebe e paga em BRL, por PIX. México (SPEI, em MXN) e USDT: em breve.